# Grafana version 12 API reference You can use Grafana HTTP APIs with Amazon Managed Grafana workspaces. The following sections describe how to use the APIs, and then list which Grafana APIs are supported. **Note** Amazon Managed Grafana also provides AWS APIs for creating and managing workspaces. For more information about the AWS APIs, see the [Amazon Managed Grafana API Reference](https://docs.aws.amazon.com/grafana/latest/APIReference/Welcome.html). **Topics** + [Authenticate with service accounts](v12-authenticating-grafana-apis.md) + [New API structure](v12-Grafana-API-new-structure.md) + [Annotations API](v12-Grafana-API-Annotations.md) + [Alerting Notification Channels API](v12-Grafana-API-AlertingNotificationChannels.md) + [Dashboard API](v12-Grafana-API-Dashboard.md) + [Dashboard Permissions API](v12-Grafana-API-DashboardPermissions.md) + [Dashboard Versions API](v12-Grafana-API-DashboardVersions.md) + [Data Source API](v12-Grafana-API-Datasource.md) + [Data Source Permissions API](v12-Grafana-API-DatasourcePermissions.md) + [External Group Synchronization API](v12-Grafana-API-ExternalGroupSynchronization.md) + [Folder API](v12-Grafana-API-Folder.md) + [Folder/Dashboard Search API](v12-Grafana-API-FolderDashboard-Search.md) + [Folder Permissions API](v12-Grafana-API-FolderPermissions.md) + [Organization API](v12-Grafana-API-Organization.md) + [Playlist API](v12-Grafana-API-Playlist.md) + [Plugin API](v12-Grafana-API-Plugin.md) + [Preferences API](v12-Grafana-API-Preferences.md) + [Snapshot API](v12-Grafana-API-Snapshot.md) + [Short URL API](v12-Grafana-API-ShortURL.md) + [Team API](v12-Grafana-API-Team.md) + [User API](v12-Grafana-API-User.md) # Authenticate with service accounts ## Using service accounts To use a Grafana API with your Amazon Managed Grafana workspace, you must have a valid service account token. Service accounts are used to run automated workloads in Grafana, such as dashboard provisioning, configuration, or report generation. Create service accounts and tokens to authenticate applications, such as Terraform, with the Grafana console or the [Amazon Managed Grafana API](https://docs.aws.amazon.com/grafana/latest/APIReference/API_CreateWorkspaceServiceAccount.html). A common use case for creating a service account is to perform operations on automated or triggered tasks. You can use service accounts to: + Define alerts in your system to be used in Grafana + Interact with Grafana without signing in as a user **Note** Each service account is considered a user for billing purposes. ### Service account tokens A service account token is a generated string that acts as a key to authenticate with Grafana’s HTTP API. When you create a service account, you can associate one or more access tokens with it. You can use service account tokens to access Grafana HTTP APIs programmatically. You can create multiple tokens for the same service account. You might want to do this if: + multiple applications use the same permissions, but you would like to audit or manage their actions separately. + you need to rotate or replace a compromised token. Service account access tokens inherit permissions from the service account. Amazon Managed Grafana has a [quota](AMG_quotas.md) on the number of service account tokens you can have at one time. This includes active and expired tokens. You must delete tokens to remove them from your quota. ### Service account benefits Service accounts provide the following benefits: + Service accounts resemble Grafana users and can be enabled/disabled, granted specific permissions, and remain active until they are deleted or disabled. + Service accounts can be associated with multiple tokens. + Service account tokens are not associated with a specific user, which means that applications can be authenticated even if a Grafana user is deleted. + You can grant permissions to service accounts in the same way that you grant permissions to users. For more information about permissions, see [Using permissions](Grafana-permissions.md). ### Creating a service account **Note** The user who creates a service account is also able to read, update and delete the service account that they created, as well as permissions associated with that service account. **Prerequisite** Ensure you have permission to create and edit service accounts. By default, the organization administrator role is required to create and edit service accounts. For more information about permissions, see [Using permissions](Grafana-permissions.md). **To create a service account** 1. Sign in to your Amazon Managed Grafana workspace and select **Administration** from the left-side menu. 1. Select **Service accounts**. 1. Select **Add service account**. 1. Enter a **Display name**. 1. The display name must be unique as it determines the ID associated with the service account. + We recommend that you use a consistent naming convention when you name service accounts. A consistent naming convention can help you scale and maintain service accounts in the future. + You can change the display name at any time. 1. Choose **Create**. **Note** You can also create service accounts using the Amazon Managed Grafana AWS APIs. Use the [CreateWorkspaceServiceAccount](https://docs.aws.amazon.com/grafana/latest/APIReference/API_CreateWorkspaceServiceAccount.html) to create a service account programmatically. ### Adding a token to a service account A service account token is a generated random string that acts as an alternative to a password when authenticating with Grafana’s HTTP API. **Prerequisite** Ensure you have permission to create and edit service accounts. By default, the organization administrator role is required to create and edit service accounts. For more information about permissions, see [Using permissions](Grafana-permissions.md). **To add a token to a service account** 1. Sign in to your Grafana workspace and choose **Administration** in the left-side menu. 1. Expand the **Users and Access** menu. 1. Choose **Service accounts**. 1. Select the service account to which you want to add a token. 1. Choose **Add service account token**. 1. Enter a name for the token. 1. Select **Set expiration date** and enter an expiration date for the token. + The expiration date specifies how long you want the key to be valid. + You can set an expiration date up to 30 days in the future. + If you are unsure of an expiration date, we recommend that you set the token to expire after a short time, such as a few hours or less. This limits the risk associated with a token that is valid for a long time. 1. Choose **Generate token**. **Note** You can also create service account tokens using the Amazon Managed Grafana AWS APIs. Use the [CreateWorkspaceServiceAccountToken](https://docs.aws.amazon.com/grafana/latest/APIReference/API_CreateWorkspaceServiceAccountToken.html) to create a service account token programmatically. ### Delete a service token When you are done with a service token, you must delete it to remove it from your workspace. Expired, but not yet deleted, tokens count toward your [quota](AMG_quotas.md) of service account tokens. **Prerequisite** Ensure you have permission to create and edit service accounts. By default, the organization administrator role is required to create and edit service accounts. For more information about permissions, see [Using permissions](Grafana-permissions.md). **To remove a token to a service account** 1. Sign in to your Grafana workspace and choose **Administration** in the left-side menu. 1. Expand the **Users and Access** menu. 1. Choose **Service accounts**. 1. Select the service account from which you want to delete a token. 1. In the list of tokens, select the red icon with an **x** next to the service account token you wish to delete. 1. Select **Delete**. Your token is deleted. **Note** You can also delete service account tokens using the Amazon Managed Grafana AWS APIs. Use the [DeleteWorkspaceServiceAccountToken](https://docs.aws.amazon.com/grafana/latest/APIReference/API_DeleteWorkspaceServiceAccountToken.html) to delete a service account token programmatically. ### Assign roles to a service account You can assign roles to a Grafana service account to control access for the associated service account tokens. You can assign roles to a service account using the Grafana UI or via the API. **Prerequisite** Ensure you have permission to create and edit service accounts. By default, the organization administrator role is required to create and edit service accounts. For more information about permissions, see [Using permissions](Grafana-permissions.md). **To assign a role to a service account** 1. Sign in to Grafana and choose **Administration** in the left-side menu. 1. Choose **Service accounts**. 1. Select the service account to which you want to assign a role. As an alternative, find the service account in the list view. 1. Assign a role using the role picker to update. # New API structure Starting in Grafana version 12, Grafana HTTP APIs are transitioning to a new standardized API structure with consistent versioning. The new APIs follow a Kubernetes-style path format: ``` /apis///namespaces/default/[/] ``` Where: + **group** – Organizes related functionality into logical collections. For example, `playlist.grafana.app` for playlist operations. + **version** – Uses semantic versioning with stability levels: `v1alpha1` (experimental), `v1beta1` (pre-release), and `v1` (GA, stable with backward compatibility guarantees). + **resource** – The resource type, such as `playlists` or `dashboards`. + **name** – The unique identifier for a specific resource instance. Used for Get, Update, and Delete operations. API responses follow a standardized format with `kind`, `apiVersion`, `metadata`, and `spec` fields. For more information about the new API structure, see [New API Structure](https://grafana.com/docs/grafana/latest/developer-resources/api-reference/http-api/apis/) in the *Grafana Labs documentation*. # Annotations API Use the Annotations API to create, update, delete, and work with annotations in the Amazon Managed Grafana workspace. Annotations are saved in the workspace's Grafana database (sqlite, mysql or postgres). Annotations can be global annotations that can be shown on any dashboard by configuring an annotation data source. Annotations are filtered by tags. Or they can be tied to a panel on a dashboard, and displayed only on that panel. **Note** To use a Grafana API with your Amazon Managed Grafana workspace, you must have a valid service account token. You include this in the `Authorization` field in the API request. ## Find annotations ``` GET /api/annotations?from=1506676478816&to=1507281278816&tags=tag1&tags=tag2&limit=100 ``` **Example request** ``` GET /api/annotations?from=1506676478816&to=1507281278816&tags=tag1&tags=tag2&limit=100 HTTP/1.1 Accept: application/json Content-Type: application/json Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk ``` Query parameters: + **from**— (Optional) Epoch datetime in milliseconds. + **to**— (Optional) Epoch datetime in milliseconds. + **limit**— (Optional) Maximum number of results returned. The default is 100. + **alertid**— (Optional) FInd annotations for the specified alert. + **dashboardId**— (Optional) Find annotations that are scoped to the specified dashboard. + **panelId**— (Optional) Find annotations that are scoped to the specified panel. + **userId**— (Optional) Find annotations created by the specified user. + **type**— (Optional) Specify to return alerts or user-created annotations. Value values are `alert` and `annotation`. + **tags**— (Optional) Use this to filter global annotations. Global annotations are annotations from an annotation data source that are not connected specifically to a dashboard or panel. To do an “AND” filtering with multiple tags, specify the tags parameter multiple times. For example, `tags=tag1&tags=tag2`. These are Grafana tags, not AWS tags. **Example response** ``` HTTP/1.1 200 Content-Type: application/json [ { "id": 1124, "alertId": 0, "dashboardId": 468, "panelId": 2, "userId": 1, "userName": "", "newState": "", "prevState": "", "time": 1507266395000, "timeEnd": 1507266395000, "text": "test", "metric": "", "tags": [ "tag1", "tag2" ], "data": {} }, { "id": 1123, "alertId": 0, "dashboardId": 468, "panelId": 2, "userId": 1, "userName": "", "newState": "", "prevState": "", "time": 1507265111000, "text": "test", "metric": "", "tags": [ "tag1", "tag2" ], "data": {} } ] ``` ## Create annotation ``` POST /api/annotations ``` Creates an annotation in the workspace's Grafana database. The `dashboardId` and `panelId` fields are optional. If they are not specified, a global annotation is created and can be queried in any dashboard that adds the Grafana annotations data source. When creating a region annotation, be sure to include the `timeEnd` property. The format for `time` and `timeEnd` should be epoch numbers in millisecond resolution. **Example request** ``` POST /api/annotations HTTP/1.1 Accept: application/json Content-Type: application/json Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk { "dashboardId":468, "panelId":1, "time":1507037197339, "timeEnd":1507180805056, "tags":["tag1","tag2"], "text":"Annotation Description" } ``` **Example response** ``` HTTP/1.1 200 Content-Type: application/json { "message":"Annotation added", "id": 1, } ``` ## Create annotation in graphite format ``` POST /api/annotations/graphite ``` Creates an annotation by using a Graphite-compatible event format. The `when` and `data` fields are optional. If `when` is not specified, the current time is used as annotation’s timestamp. The `tags` field can also be in prior to Graphite 0.10.0 format (string with multiple tags being separated by a space). **Example request** ``` POST /api/annotations/graphite HTTP/1.1 Accept: application/json Content-Type: application/json Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk { "what": "Event - deploy", "tags": ["deploy", "production"], "when": 1467844481, "data": "deploy of master branch happened at Wed Jul 6 22:34:41 UTC 2016" } ``` **Example response** ``` HTTP/1.1 200 Content-Type: application/json { "message":"Graphite annotation added", "id": 1 } ``` ## Update annotation ``` PUT /api/annotations/:id ``` pdates all properties of an annotation that matches the specified id. To only update certain properties, use the Patch Annotation operation. **Example request** ``` PUT /api/annotations/1141 HTTP/1.1 Accept: application/json Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk Content-Type: application/json { "time":1507037197339, "timeEnd":1507180805056, "text":"Annotation Description", "tags":["tag3","tag4","tag5"] } ``` **Example response:** ``` HTTP/1.1 200 Content-Type: application/json { "message":"Annotation updated" } ``` ## Patch annotation ``` PATCH /api/annotations/:id ``` Updates one or more properties of an annotation that matches the specified id. This operation currently supports updating the `text`, `tags`, `time`, and `timeEnd` properties. **Example request:** ``` PATCH /api/annotations/1145 HTTP/1.1 Accept: application/json Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk Content-Type: application/json { "text":"New Annotation Description", "tags":["tag6","tag7","tag8"] } ``` **Example response** ``` HTTP/1.1 200 Content-Type: application/json { "message":"Annotation patched" } ``` ## Delete annotation by Id ``` DELETE /api/annotations/:id ``` Deletes the annotation that matches the specified Id. **Example request** ``` DELETE /api/annotations/1 HTTP/1.1 Accept: application/json Content-Type: application/json Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk ``` **Example response** ``` HTTP/1.1 200 Content-Type: application/json { "message":"Annotation deleted" } ``` # Alerting Notification Channels API Use the Alerting Notification Channels API to create, update, delete, and retrieve notification channels. The identifier (id) of a notification channel is an auto-incrementing numeric value and is only unique per workspace. The unique identifier (uid) of a notification channel can be used to uniquely identify a folder between multiple workspaces. It’s automatically generated if you don't provide one when you create a notification channel. The uid allows having consistent URLs for accessing notification channels and when synchronizing notification channels between multiple Amazon Managed Grafana workspaces. **Note** To use a Grafana API with your Amazon Managed Grafana workspace, you must have a valid service account token. You include this in the `Authorization` field in the API request. ## Get all notification channels Returns all notification channels that the authenticated user has permission to view. ``` GET /api/alert-notifications ``` **Example request** ``` GET /api/alert-notifications HTTP/1.1 Accept: application/json Content-Type: application/json Authorization: Bearer 1234abcd567exampleToken890 ``` **Example response** ``` HTTP/1.1 200 Content-Type: application/json [ { "id": 1, "uid": "sns-uid", "name": "test", "type": "sns", "isDefault": false, "sendReminder": false, "disableResolveMessage": false, "frequency": "", "created": "2023-09-08T19:57:56Z", "updated": "2023-09-08T19:57:56Z", "settings": { "authProvider": "default", "autoResolve": true, "httpMethod": "POST", "messageFormat": "json", "severity": "critical", "topic": "", "uploadImage": false }, "secureFields": {} } ] ``` ## Get all notification channels (lookup) Returns all notification channels, but with less detailed information. Accessible by any authenticated user and is mainly used to provide alert notification channels in the Grafana workspace console UI when configuring alert rules. ``` GET /api/alert-notifications/lookup ``` **Example request** ``` GET /api/alert-notifications/lookup HTTP/1.1 Accept: application/json Content-Type: application/json Authorization: Bearer 1234abcd567exampleToken890 ``` **Example response** ``` HTTP/1.1 200 Content-Type: application/json [ { "id": 1, "uid": "sns-uid", "name": "test", "type": "sns", "isDefault": false }, { "id": 2, "uid": "slack-uid", "name": "Slack", "type": "slack", "isDefault": false } ] ``` ## Get all notification channels by UID ``` GET /api/alert-notifications/uid/:uid ``` **Example request** ``` GET /api/alert-notifications/uid/sns-uid HTTP/1.1 Accept: application/json Content-Type: application/json Authorization: Bearer 1234abcd567exampleToken890 ``` **Example response** ``` HTTP/1.1 200 Content-Type: application/json { "id": 1, "uid": "sns-uid", "name": "test", "type": "sns", "isDefault": false, "sendReminder": false, "disableResolveMessage": false, "frequency": "", "created": "2023-09-08T19:57:56Z", "updated": "2023-09-08T19:57:56Z", "settings": { "authProvider": "default", "autoResolve": true, "httpMethod": "POST", "messageFormat": "json", "severity": "critical", "topic": "", "uploadImage": false }, "secureFields": {} } ``` ## Get all notification channels by Id ``` GET /api/alert-notifications/:id ``` **Example request** ``` GET /api/alert-notifications/1 HTTP/1.1 Accept: application/json Content-Type: application/json Authorization: Bearer 1234abcd567exampleToken890 ``` **Example response** ``` HTTP/1.1 200 Content-Type: application/json { "id": 1, "uid": "sns-uid", "name": "test", "type": "sns", "isDefault": false, "sendReminder": false, "disableResolveMessage": false, "frequency": "", "created": "2023-09-08T19:57:56Z", "updated": "2023-09-08T19:57:56Z", "settings": { "authProvider": "default", "autoResolve": true, "httpMethod": "POST", "messageFormat": "json", "severity": "critical", "topic": "", "uploadImage": false }, "secureFields": {} } ``` ## Create notification channel To see what notification channels are supported by Amazon Managed Grafana, see the list of supported notifiers in [Working with contact points](alert-contact-points.md). In Grafana version 12, use the Alerting Provisioning API to create contact points. The legacy `/api/alert-notifications` endpoint is no longer available. **Example request** ``` POST /api/v1/provisioning/contact-points HTTP/1.1 Accept: application/json Content-Type: application/json Authorization: Bearer 1234abcd567exampleToken890 { "uid": "new-sns-uid", "name": "sns alert notification", "type": "sns", "isDefault": false, "sendReminder": false, "settings": { "topic_arn": "", "subject": "" } } ``` ## Update notification channel by UID ``` PUT /api/alert-notifications/uid/:uid ``` **Example request** ``` PUT /api/alert-notifications/uid/sns-uid HTTP/1.1 Accept: application/json Content-Type: application/json Authorization: Bearer 1234abcd567exampleToken890 { "uid": "sns-uid", // optional "name": "sns alert notification", //Required "type": "sns", //Required "isDefault": false, "sendReminder": true, "frequency": "15m", "settings": { "authProvider": "default", "autoResolve": true, "httpMethod": "POST", "messageFormat": "json", "severity": "critical", "topic": "", "uploadImage": false } } ``` **Example response** ``` HTTP/1.1 200 Content-Type: application/json { "id": 1, "uid": "sns-uid", "name": "sns alert notification", "type": "sns", "isDefault": false, "sendReminder": true, "frequency": "15m", "settings": { "authProvider": "default", "autoResolve": true, "httpMethod": "POST", "messageFormat": "json", "severity": "critical", "topic": "", "uploadImage": false }, "created": "2017-01-01 12:34", "updated": "2017-01-01 12:34" } ``` ## Update notification channel by Id ``` PUT /api/alert-notifications/:id ``` **Example request** ``` PUT /api/alert-notifications/1 HTTP/1.1 Accept: application/json Content-Type: application/json Authorization: Bearer 1234abcd567exampleToken890 { "id": 1, "uid": "sns-uid", // optional "name": "sns alert notification", //Required "type": "sns", //Required "isDefault": false, "sendReminder": true, "frequency": "15m", "settings": { "authProvider": "default", "autoResolve": true, "httpMethod": "POST", "messageFormat": "json", "severity": "critical", "topic": "", "uploadImage": false } } ``` **Example response** ``` HTTP/1.1 200 Content-Type: application/json { "id": 1, "uid": "sns-uid", "name": "sns alert notification", "type": "sns", "isDefault": false, "sendReminder": true, "frequency": "15m", "settings": { "authProvider": "default", "autoResolve": true, "httpMethod": "POST", "messageFormat": "json", "severity": "critical", "topic": "", "uploadImage": false }, "created": "2017-01-01 12:34", "updated": "2017-01-01 12:34" } ``` ## Delete notification channel by UID ``` DELETE /api/alert-notifications/uid/:uid ``` **Example request** ``` DELETE /api/alert-notifications/uid/sns-uid HTTP/1.1 Accept: application/json Content-Type: application/json Authorization: Bearer 1234abcd567exampleToken890 ``` **Example response** ``` HTTP/1.1 200 Content-Type: application/json { "message": "Notification deleted" } ``` ## Delete notification channel by Id ``` DELETE /api/alert-notifications/:id ``` **Example request** ``` DELETE /api/alert-notifications/1 HTTP/1.1 Accept: application/json Content-Type: application/json Authorization: Bearer 1234abcd567exampleToken890 ``` **Example response** ``` HTTP/1.1 200 Content-Type: application/json { "message": "Notification deleted" } ``` ## Test notification channel Sends a test notification message for the given notification channel type and settings. ``` POST /api/alert-notifications/test ``` **Example request** ``` POST /api/alert-notifications/test HTTP/1.1 Accept: application/json Content-Type: application/json Authorization: Bearer 1234abcd567exampleToken890 { "type": "sns", "settings": { "authProvider": "default", "autoResolve": true, "httpMethod": "POST", "messageFormat": "json", "severity": "critical", "topic": "", "uploadImage": false } } ``` **Example response** ``` HTTP/1.1 200 Content-Type: application/json { "message": "Test notification sent" } ``` # Dashboard API Use the Dashboard API to create, update, delete, and work with dashboards in the Amazon Managed Grafana workspace. The identifier (id) of a dashboard is an auto-incrementing numeric value and is only unique per workspace. The unique identifier (uid) of a dashboard can be used to uniquely identify a dashboard between multiple Amazon Managed Grafana workspaces. It’s automatically generated if you don't provide one when you create a dashboard. The uid allows having consistent URLs for accessing dashboards and when synchronizing dashboards between multiple workspaces. The use of the uid means that changing the title of a dashboard does not break any bookmarked links to that dashboard. The uid can have a maximum length of 40 characters. **Note** To use a Grafana API with your Amazon Managed Grafana workspace, you must have a valid service account token. You include this in the `Authorization` field in the API request. ## Create/Update dashboard ``` POST /api/dashboards/db ``` Creates a new dashboard or updates an existing dashboard. **Example request to create a new dashboard** ``` POST /api/dashboards/db HTTP/1.1 Accept: application/json Content-Type: application/json Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk { "dashboard": { "id": null, "uid": null, "title": "Production Overview", "tags": [ "templated" ], "timezone": "browser", "schemaVersion": 16, "version": 0, "refresh": "25s" }, "folderId": 0, "folderUid": "l3KqBxCMz", "message": "Made changes to xyz", "overwrite": false } ``` JSON body schema: + **dashboard**— The complete dashboard model. Use null to create a new dashboard. + **dashboard.id**— Use null to create a new dashboard. + **dashboard.uid**— Optional unique identifer when you use this to create a new dashboard. If null, a new uid is generated. + **folderid**— The id of the folder to save the dashboard in. + **folderUid**— The Uid of the folder to save the dashboard in. Overrides the value of `folderid` + **overwrite**— Specify `true` to overwrite an existing dashboard with a newer version, same dashboard title in folder or same dashboard uid. + **message**— Set a commit message for the version history. + **refresh**— Set the dashboard refresh interval. If this is lower than the minimum refresh interval, it is ignored and the minimum refresh interval is used. To add or update an alert rule for a dashboard panel, declare a `dashboard.panels.alert` block. **Example request to update a dashboard alert rule** ``` HTTP/1.1 200 OK Content-Type: application/json; charset=UTF-8 Content-Length: 78 { "dashboard": { "id": 104, "panels": [ { "alert": { "alertRuleTags": {}, "conditions": [ { "evaluator": { "params": [ 25 ], "type": "gt" }, "operator": { "type": "and" }, "query": { "params": [ "A", "5m", "now" ] }, "reducer": { "params": [], "type": "avg" }, "type": "query" } ], "executionErrorState": "alerting", "for": "5m", "frequency": "1m", "handler": 1, "name": "Panel Title alert", "noDataState": "no_data", "notifications": [] }, "aliasColors": {}, "bars": false, "dashLength": 10, "dashes": false, "datasource": null, "fieldConfig": { "defaults": { "custom": {} }, "overrides": [] }, "fill": 1, "fillGradient": 0, "gridPos": { "h": 9, "w": 12, "x": 0, "y": 0 }, "hiddenSeries": false, "id": 2, "legend": { "avg": false, "current": false, "max": false, "min": false, "show": true, "total": false, "values": false }, "lines": true, "linewidth": 1, "nullPointMode": "null", "options": { "dataLinks": [] }, "percentage": false, "pointradius": 2, "points": false, "renderer": "flot", "seriesOverrides": [], "spaceLength": 10, "stack": false, "steppedLine": false, "targets": [ { "refId": "A", "scenarioId": "random_walk" } ], "thresholds": [ { "colorMode": "critical", "fill": true, "line": true, "op": "gt", "value": 50 } ], "timeFrom": null, "timeRegions": [], "timeShift": null, "title": "Panel Title", "tooltip": { "shared": true, "sort": 0, "value_type": "individual" }, "type": "graph", "xaxis": { "buckets": null, "mode": "time", "name": null, "show": true, "values": [] }, "yaxes": [ { "format": "short", "label": null, "logBase": 1, "max": null, "min": null, "show": true }, { "format": "short", "label": null, "logBase": 1, "max": null, "min": null, "show": true } ], "yaxis": { "align": false, "alignLevel": null } } ], "title": "Update alert rule via API", "uid": "dHEquNzGz", "version": 1 } } ``` **Example response** ``` HTTP/1.1 200 OK Content-Type: application/json; charset=UTF-8 Content-Length: 78 { "id": 1, "uid": "cIBgcSjkk", "url": "/d/cIBgcSjkk/production-overview", "status": "success", "version": 1, "slug": "production-overview" //deprecated in Grafana v5.0 } ``` Status Codes: + **200**— Created + **400**— Error such as invalid JSON, invalid or missing fields + **401**— Unauthorized + **403**— Access denied + **412**— Precondition failed The **412** status code is used to explain why the dashboard can't be created. + The dashboard has been changed by someone else `status=version-mismatch` + A dashboard with the same name in the folder already exists `status=name-exists` + A dashboard with the same uid already exists `status=name-exists` + The dashboard belongs to plugin `plugin title` `status=plugin-dashboard` The response body has the following properties. If another dashboard has the same title, the `status` value is `name-exists`. ``` HTTP/1.1 412 Precondition Failed Content-Type: application/json; charset=UTF-8 Content-Length: 97 { "message": "The dashboard has been changed by someone else", "status": "version-mismatch" } ``` ## Get dashboard by uid ``` GET /api/dashboards/uid/:uid ``` Returns the dashboard matching the uid. The metadata returned might contain information about the UID of the folder that contains the dashboard. **Example request** ``` GET /api/dashboards/uid/cIBgcSjkk HTTP/1.1 Accept: application/json Content-Type: application/json Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk ``` **Example response** ``` HTTP/1.1 200 Content-Type: application/json { "dashboard": { "id": 1, "uid": "cIBgcSjkk", "title": "Production Overview", "tags": [ "templated" ], "timezone": "browser", "schemaVersion": 16, "version": 0 }, "meta": { "isStarred": false, "url": "/d/cIBgcSjkk/production-overview", "folderId": 2, "folderUid": "l3KqBxCMz", "slug": "production-overview" //deprecated in Grafana v5.0 } } ``` Status Codes: + **200**— Found + **401**— Unauthorized + **403**— Access denied + **404**— Not found ## Delete dashboard by uid ``` DELETE /api/dashboards/uid/:uid ``` Deletes the dashboard matching the uid. **Example request** ``` DELETE /api/dashboards/uid/cIBgcSjkk HTTP/1.1 Accept: application/json Content-Type: application/json Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk ``` **Example response** ``` HTTP/1.1 200 Content-Type: application/json { "title": "Production Overview", "message": "Dashboard Production Overview deleted", "id": 2 } ``` Status Codes: + **200**— Deleted + **401**— Unauthorized + **403**— Access denied + **404**— Not found ## Gets the home dashboard ``` GET /api/dashboards/home ``` Returns the home dashboard. **Example request** ``` GET /api/dashboards/home HTTP/1.1 Accept: application/json Content-Type: application/json Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk ``` **Example response** ``` HTTP/1.1 200 Content-Type: application/json { "dashboard": { "editable":false, "hideControls":true, "nav":[ { "enable":false, "type":"timepicker" } ], "style":"dark", "tags":[], "templating":{ "list":[ ] }, "time":{ }, "timezone":"browser", "title":"Home", "version":5 }, "meta": { "isHome":true, "canSave":false, "canEdit":false, "canStar":false, "url":"", "expires":"0001-01-01T00:00:00Z", "created":"0001-01-01T00:00:00Z" } } ``` ## Get dashboard tags ``` GET /api/dashboards/tags ``` Returns all tags of dashboards. **Example request** ``` GET /api/dashboards/tags HTTP/1.1 Accept: application/json Content-Type: application/json Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk ``` **Example response** ``` HTTP/1.1 200 Content-Type: application/json [ { "term":"tag1", "count":1 }, { "term":"tag2", "count":4 } ] ``` # Dashboard Permissions API Use the Dashboard Permissions API to update or retrieve the permissions for a dashboard. Permissions with `dashboardId=-1` are the default permissions for users with the Viewer and Editor roles. Permissions can be set for a user, a team or a role (Viewer or Editor). Permissions cannot be set for Admins - they always have access to everything. The permission levels for the `permission` field are as follows: + 1 = View + 2 = Edit + 4 = Admin **Note** To use a Grafana API with your Amazon Managed Grafana workspace, you must have a valid service account token. You include this in the `Authorization` field in the API request. ## Get permissions for a dashboard ``` GET /api/dashboards/id/:dashboardId/permissions ``` Gets all existing permissions for the dashboard with the given `dashboardId`. **Example request** ``` GET /api/dashboards/id/1/permissions HTTP/1.1 Accept: application/json Content-Type: application/json Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk ``` **Example response** ``` HTTP/1.1 200 OK Content-Type: application/json; charset=UTF-8 Content-Length: 551 [ { "id": 1, "dashboardId": -1, "created": "2017-06-20T02:00:00+02:00", "updated": "2017-06-20T02:00:00+02:00", "userId": 0, "userLogin": "", "userEmail": "", "teamId": 0, "team": "", "role": "Viewer", "permission": 1, "permissionName": "View", "uid": "", "title": "", "slug": "", "isFolder": false, "url": "" }, { "id": 2, "dashboardId": -1, "created": "2017-06-20T02:00:00+02:00", "updated": "2017-06-20T02:00:00+02:00", "userId": 0, "userLogin": "", "userEmail": "", "teamId": 0, "team": "", "role": "Editor", "permission": 2, "permissionName": "Edit", "uid": "", "title": "", "slug": "", "isFolder": false, "url": "" } ] ``` Status Codes: + **200**— OK + **401**— Unauthorized + **403**— Access denied + **404**— Dashboard not found ## Update permissions for a dashboard ``` POST /api/dashboards/id/:dashboardId/permissions ``` Updates the permissions for a dashboard. This operation removes existing permissions if they are not included in the request. **Example request** ``` POST /api/dashboards/id/1/permissions Accept: application/json Content-Type: application/json Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk { "items": [ { "role": "Viewer", "permission": 1 }, { "role": "Editor", "permission": 2 }, { "teamId": 1, "permission": 1 }, { "userId": 11, "permission": 4 } ] } ``` JSON body schema: + **items**— The permission items to add or update. Existing items that are omitted from the list are removed. **Example response** ``` HTTP/1.1 200 OK Content-Type: application/json; charset=UTF-8 Content-Length: 35 {"message":"Dashboard permissions updated"} ``` Status Codes: + **200**— Created + **401**— Unauthorized + **403**— Access denied + **404**— Dashboard not found # Dashboard Versions API Use the Dashboard Versions API to retrieve dashboard versions and restore a dashboard to a specified version. **Note** To use a Grafana API with your Amazon Managed Grafana workspace, you must have a valid service account token. You include this in the `Authorization` field in the API request. ## Get all dashboard versions ``` GET /api/dashboards/uid/:uid/versions ``` Gets all existing dashboard versions for the dashboard with the given `uid`. Query parameters: + **limit**— Maximum number of results to return. + **start**— Version to start from when returning queries. **Example request** ``` GET /api/dashboards/id/1/versions?limit=2?start=0 HTTP/1.1 Accept: application/json Content-Type: application/json Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk ``` **Example response** ``` HTTP/1.1 200 OK Content-Type: application/json; charset=UTF-8 Content-Length: 428 [ { "id": 2, "dashboardId": 1, "parentVersion": 1, "restoredFrom": 0, "version": 2, "created": "2017-06-08T17:24:33-04:00", "createdBy": "admin", "message": "Updated panel title" }, { "id": 1, "dashboardId": 1, "parentVersion": 0, "restoredFrom": 0, "version": 1, "created": "2017-06-08T17:23:33-04:00", "createdBy": "admin", "message": "Initial save" } ] ``` Status Codes: + **200**— OK + **400**— Errors + **401**— Unauthorized + **404**— Dashboard version not found ## Get dashboard version ``` GET /api/dashboards/uid/:uid/versions/:id ``` Get the dashboard version with the given id, for the dashboard with the given `dashboardId`. **Example request** ``` GET /api/dashboards/id/1/versions/1 HTTP/1.1 Accept: application/json Content-Type: application/json Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk ``` **Example response** ``` HTTP/1.1 200 OK Content-Type: application/json; charset=UTF-8 Content-Length: 1300 { "id": 1, "dashboardId": 1, "parentVersion": 0, "restoredFrom": 0, "version": 1, "created": "2017-04-26T17:18:38-04:00", "message": "Initial save", "data": { "annotations": { "list": [ ] }, "editable": true, "gnetId": null, "graphTooltip": 0, "hideControls": false, "id": 1, "links": [ ], "rows": [ { "collapse": false, "height": "250px", "panels": [ ], "repeat": null, "repeatIteration": null, "repeatRowId": null, "showTitle": false, "title": "Dashboard Row", "titleSize": "h6" } ], "schemaVersion": 14, "style": "dark", "tags": [ ], "templating": { "list": [ ] }, "time": { "from": "now-6h", "to": "now" }, "timepicker": { "refresh_intervals": [ "5s", "10s", "30s", "1m", "5m", "15m", "30m", "1h", "2h", "1d" ], "time_options": [ "5m", "15m", "1h", "6h", "12h", "24h", "2d", "7d", "30d" ] }, "timezone": "browser", "title": "test", "version": 1 }, "createdBy": "admin" } ``` Status Codes: + **200**— OK + **401**— Unauthorized + **404**— Dashboard version not found ## Restore dashboard ``` POST /api/dashboards/uid/:uid/restore ``` Restores a dashboard to the dashboard version that you specify. **Example request** ``` POST /api/dashboards/id/1/restore Accept: application/json Content-Type: application/json Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk { "version": 1 } ``` JSON body schema: + **version**— The dashboard version to restore to. **Example response** ``` HTTP/1.1 200 OK Content-Type: application/json; charset=UTF-8 Content-Length: 67 { "slug": "my-dashboard", "status": "success", "version": 3 } ``` JSON response body schema: + **slug**— The URL-friendly slug of the dashboard's title. + **status**— Whether the restore was successful or not. + **version**— The new dashboard version following the restore. Status Codes: + **200**— Created + **401**— Unauthorized + **404**— Dashboard or dashboard version not found + **500**— Internal server error (indicates issue retrieving dashboard tags from database) Example error response: ``` HTTP/1.1 404 Not Found Content-Type: application/json; charset=UTF-8 Content-Length: 46 { "message": "Dashboard version not found" } ``` JSON response body schema: + **message**— A message explaining the reason for the failure. ## Compare dashboard versions ``` POST /api/dashboards/calculate-diff ``` Compares two dashboard versions by calculating the JSON diff of them. **Example request** ``` POST /api/dashboards/calculate-diff HTTP/1.1 Accept: text/html Content-Type: application/json Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk { "base": { "dashboardId": 1, "version": 1 }, "new": { "dashboardId": 1, "version": 2 }, "diffType": "json" } ``` JSON body schema: + **base**— An object representing the base dashboard version. + **new**— An object representing the new dashboard version. + **difftype**— The type of diff to return. Valid values are `json` and `basic`. Example response (JSON diff) ``` HTTP/1.1 200 OK Content-Type: text/html; charset=UTF-8

``` The response is a textual representation of the diff, with the dashboard values being in JSON, similar to the diffs seen on sites like GitHub or GitLab. Status Codes: + **200**— OK + **200**— Bad request, invalid JSON sent + **401**— Unauthorized + **404**— Not found Example response (Basic diff) ``` HTTP/1.1 200 OK Content-Type: text/html; charset=UTF-8
``` The response is a summary of the changes, derived from the diff between the two JSON objects. Status Codes: + **200**— OK + **200**— Bad request, invalid JSON sent + **401**— Unauthorized + **404**— Not found # Data Source API Use the Data Source API to create, update, delete, and work with data sources in the Amazon Managed Grafana workspace. **Note** To use a Grafana API with your Amazon Managed Grafana workspace, you must have a valid service account token. You include this in the `Authorization` field in the API request. ## Get all data sources ``` GET /api/datasources ``` **Example request** ``` GET /api/datasources HTTP/1.1 Accept: application/json Content-Type: application/json Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk ``` **Example response** ``` HTTP/1.1 200 Content-Type: application/json [ { "id": 1, "orgId": 1, "uid": "H8joYFVGz" "name": "datasource_elastic", "type": "elasticsearch", "typeLogoUrl": "public/app/plugins/datasource/elasticsearch/img/elasticsearch.svg", "access": "proxy", "url": "http://mydatasource.com", "password": "", "user": "", "database": "grafana-dash", "basicAuth": false, "isDefault": false, "jsonData": { "esVersion": 5, "logLevelField": "", "logMessageField": "", "maxConcurrentShardRequests": 256, "timeField": "@timestamp" }, "readOnly": false } ] ``` ## Get a single data source by UID ``` GET /api/datasources/uid/:uid ``` **Example request** ``` GET /api/datasources/uid/kLtEtcRGk HTTP/1.1 Accept: application/json Content-Type: application/json Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk ``` **Example response** ``` HTTP/1.1 200 Content-Type: application/json { "id": 1, "uid": "kLtEtcRGk", "orgId": 1, "name": "test_datasource", "type": "graphite", "typeLogoUrl": "", "access": "proxy", "url": "http://mydatasource.com", "password": "", "user": "", "database": "", "basicAuth": false, "basicAuthUser": "", "basicAuthPassword": "", "withCredentials": false, "isDefault": false, "jsonData": { "graphiteType": "default", "graphiteVersion": "1.1" }, "secureJsonFields": {}, "version": 1, "readOnly": false } ``` ## Get a single data source by name ``` GET /api/datasources/name/:name ``` **Example request** ``` GET /api/datasources/name/test_datasource HTTP/1.1 Accept: application/json Content-Type: application/json Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk ``` **Example response** ``` HTTP/1.1 200 Content-Type: application/json { "id": 1, "uid": "kLtEtcRGk", "orgId": 1, "name": "test_datasource", "type": "graphite", "typeLogoUrl": "", "access": "proxy", "url": "http://mydatasource.com", "password": "", "user": "", "database": "", "basicAuth": false, "basicAuthUser": "", "basicAuthPassword": "", "withCredentials": false, "isDefault": false, "jsonData": { "graphiteType": "default", "graphiteVersion": "1.1" }, "secureJsonFields": {}, "version": 1, "readOnly": false } ``` ## Get data source Id by name ``` GET /api/datasources/id/:name ``` **Example request** ``` GET /api/datasources/id/test_datasource HTTP/1.1 Accept: application/json Content-Type: application/json Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk ``` **Example response** ``` HTTP/1.1 200 Content-Type: application/json { "id":1 } ``` ## Create a data source ``` POST /api/datasources ``` **Example Graphite request** ``` POST /api/datasources HTTP/1.1 Accept: application/json Content-Type: application/json Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk { "name":"test_datasource", "type":"graphite", "url":"http://mydatasource.com", "access":"proxy", "basicAuth":false } ``` **Example Graphite response** ``` HTTP/1.1 200 Content-Type: application/json { "datasource": { "id": 1, "orgId": 1, "name": "test_datasource", "type": "graphite", "typeLogoUrl": "", "access": "proxy", "url": "http://mydatasource.com", "password": "", "user": "", "database": "", "basicAuth": false, "basicAuthUser": "", "basicAuthPassword": "", "withCredentials": false, "isDefault": false, "jsonData": {}, "secureJsonFields": {}, "version": 1, "readOnly": false }, "id": 1, "message": "Datasource added", "name": "test_datasource" } ``` **Note** When you define `password` and `basicAuthPassword` within `secureJsonData`, Amazon Managed Grafana encryptes them securely as an encrypted blob in the database. The response then lists the encrypte fields in `secureJsonFields`. **Example Graphite request with basic auth enabled** ``` POST /api/datasources HTTP/1.1 Accept: application/json Content-Type: application/json Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk { "name": "test_datasource", "type": "graphite", "url": "http://mydatasource.com", "access": "proxy", "basicAuth": true, "basicAuthUser": "basicuser", "secureJsonData": { "basicAuthPassword": "basicpassword" } } ``` **Example response with basic auth enabled** ``` HTTP/1.1 200 Content-Type: application/json { "datasource": { "id": 1, "orgId": 1, "name": "test_datasource", "type": "graphite", "typeLogoUrl": "", "access": "proxy", "url": "http://mydatasource.com", "password": "", "user": "", "database": "", "basicAuth": true, "basicAuthUser": "basicuser", "basicAuthPassword": "", "withCredentials": false, "isDefault": false, "jsonData": {}, "secureJsonFields": { "basicAuthPassword": true }, "version": 1, "readOnly": false }, "id": 102, "message": "Datasource added", "name": "test_datasource" } ``` **Example CloudWatch request** ``` POST /api/datasources HTTP/1.1 Accept: application/json Content-Type: application/json Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk { "name": "test_datasource", "type": "cloudwatch", "url": "http://monitoring.us-west-1.amazonaws.com", "access": "proxy", "jsonData": { "authType": "keys", "defaultRegion": "us-west-1" }, "secureJsonData": { "accessKey": "Ol4pIDpeKSA6XikgOl4p", "secretKey": "dGVzdCBrZXkgYmxlYXNlIGRvbid0IHN0ZWFs" } } ``` ## Update a data source by UID ``` PUT /api/datasources/uid/:uid ``` Updates the data source matching the given UID. **Example request** ``` PUT /api/datasources/uid/kLtEtcRGk HTTP/1.1 Accept: application/json Content-Type: application/json Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk { "name": "test_datasource", "type": "graphite", "url": "http://mydatasource.com", "access": "proxy", "basicAuth": false, "isDefault": false } ``` **Example response** ``` HTTP/1.1 200 Content-Type: application/json { "datasource": { "id": 1, "uid": "kLtEtcRGk", "orgId": 1, "name": "test_datasource", "type": "graphite", "access": "proxy", "url": "http://mydatasource.com", "basicAuth": false, "isDefault": false }, "name": "test_datasource" } ``` ## Delete data source by UID ``` DELETE /api/datasources/uid/:uid ``` **Example request** ``` DELETE /api/datasources/uid/kLtEtcRGk HTTP/1.1 Accept: application/json Content-Type: application/json Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk ``` **Example response** ``` HTTP/1.1 200 Content-Type: application/json {"message":"Data source deleted"} ``` ## Delete data source by name ``` DELETE /api/datasources/name/:datasourceName ``` **Example request** ``` DELETE /api/datasources/name/test_datasource HTTP/1.1 Accept: application/json Content-Type: application/json Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk ``` **Example response** ``` HTTP/1.1 200 Content-Type: application/json { "message":"Data source deleted", "id": 1 } ``` ## Data source proxy calls ``` GET /api/datasources/proxy/:datasourceId/* ``` Proxies all calls to the actual data source. ## Query data sources ``` POST /api/ds/query ``` Queries a data source having a backend implementation. Most built-in data sources have backend implementation. **Example request** ``` POST /api/ds/query HTTP/1.1 Accept: application/json Content-Type: application/json { "queries":[ { "refId":"A", "scenarioId":"csv_metric_values", "datasource":{ "uid":"PD8C576611E62080A" }, "format": "table", "maxDataPoints":1848, "intervalMs":200, "stringInput":"1,20,90,30,5,0" } ], "from":"now-5m", "to":"now" } ``` JSON body schema: + **from/to**— Specifies the time range for the queries. The time can be either epoch timestamps in milliseconds or relative using Grafana time units. For example, `now-5m`. + **queries**— Specifies one or more queries. Must contain at least 1. + **queries.datasource.uid**— Specifies the UID of data source to be queried. Each query in the request must have a unique `datasource`. + **queries.refId**— Specifies an identifier of the query. Defaults to “A”. + **queries.format**— Specifies the format the data should be returned in. Valid options are `time_series` or `table` depending on the data source. + **queries.maxDataPoints**— Species the maximum amount of data points that a dashboard panel can render. Defaults to 100. + **queries.intervalMs**— Specifies the time series time interval in milliseconds. Defaults to 1000. In addition, specific properties of each data source should be added in a request (for example **queries.stringInput** as shown in the request above). To better understand how to form a query for a certain data source, use the Developer Tools in your browser of choice and inspect the HTTP requests being made to `/api/ds/query`. **Example test data source time series query response** ``` HTTP/1.1 200 Content-Type: application/json { "results": { "A": { "frames": [ { "schema": { "refId": "A", "fields": [ { "name": "time", "type": "time", "typeInfo": { "frame": "time.Time" } }, { "name": "A-series", "type": "number", "typeInfo": { "frame": "int64", "nullable": true } } ] }, "data": { "values": [ [1644488152084, 1644488212084, 1644488272084, 1644488332084, 1644488392084, 1644488452084], [1, 20, 90, 30, 5, 0] ] } } ] } } } ``` ## Update an existing data source (deprecated) **Important** This endpoint is deprecated. Use [Update a data source by UID](#v12-Grafana-API-Datasource-updatebyUID) instead. ``` PUT /api/datasources/:datasourceId ``` **Example request** ``` PUT /api/datasources/1 HTTP/1.1 Accept: application/json Content-Type: application/json Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk { "id":1, "orgId":1, "name":"test_datasource", "type":"graphite", "access":"proxy", "url":"http://mydatasource.com", "password":"", "user":"", "database":"", "basicAuth":true, "basicAuthUser":"basicuser", "secureJsonData": { "basicAuthPassword": "basicpassword" }, "isDefault":false, "jsonData":null } ``` **Example response** ``` HTTP/1.1 200 Content-Type: application/json { "datasource": { "id": 1, "orgId": 1, "name": "test_datasource", "type": "graphite", "typeLogoUrl": "", "access": "proxy", "url": "http://mydatasource.com", "password": "", "user": "", "database": "", "basicAuth": true, "basicAuthUser": "basicuser", "basicAuthPassword": "", "withCredentials": false, "isDefault": false, "jsonData": {}, "secureJsonFields": { "basicAuthPassword": true }, "version": 1, "readOnly": false }, "id": 102, "message": "Datasource updated", "name": "test_datasource" } ``` **Note** We recommend that you define `password` and `basicAuthPassword` within `secureJsonData` so that they are stored securely as an encrypted blob in the database. The response then lists the encrypte fields in `secureJsonFields`. ## Get a single data source by Id (deprecated) **Important** This endpoint is deprecated. Use [Get a single data source by UID](#v12-Grafana-API-Datasource-getbyUID) instead. ``` GET /api/datasources/:datasourceId ``` **Example request** ``` GET /api/datasources/1 HTTP/1.1 Accept: application/json Content-Type: application/json Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk ``` **Example response** ``` HTTP/1.1 200 Content-Type: application/json { "id": 1, "uid": "kLtEtcRGk", "orgId": 1, "name": "test_datasource", "type": "graphite", "typeLogoUrl": "", "access": "proxy", "url": "http://mydatasource.com", "password": "", "user": "", "database": "", "basicAuth": false, "basicAuthUser": "", "basicAuthPassword": "", "withCredentials": false, "isDefault": false, "jsonData": { "graphiteType": "default", "graphiteVersion": "1.1" }, "secureJsonFields": {}, "version": 1, "readOnly": false } ``` ## Delete data source by Id (deprecated) **Important** This endpoint is deprecated. Use [Delete data source by UID](#v12-Grafana-API-Datasource-deletebyUID) instead. ``` DELETE /api/datasources/:datasourceId ``` **Example request** ``` DELETE /api/datasources/1 HTTP/1.1 Accept: application/json Content-Type: application/json Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk ``` **Example response** ``` HTTP/1.1 200 Content-Type: application/json {"message":"Data source deleted"} ``` # Data Source Permissions API Use the Data Source Permissions API to enable, disable, list, add, and remove permissions for data sources. You can set permissions for a user or a team. Permissions can't be set for Admins, because they always have access to everything. The permission levels for the permission field are as follows: + 1 = Query **Note** To use a Grafana API with your Amazon Managed Grafana workspace, you must have a valid service account token. You include this in the `Authorization` field in the API request. ## Enable permissions for a data source ``` POST /api/datasources/:id/enable-permissions ``` Enables permissions for the data source with the given id. No one except Org Admins are able to query the data source until permissions have been added to permit certain users or teams to query the data source. **Example request** ``` POST /api/datasources/1/enable-permissions Accept: application/json Content-Type: application/json Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk ``` **Example response** ``` HTTP/1.1 200 OK Content-Type: application/json; charset=UTF-8 Content-Length: 35 {"message":"Datasource permissions enabled"} ``` Status Codes: + **200**— Created + **400**— Permissions can't be enabled, see the response body for details. + **401**— Unauthorized + **403**— Access denied + **404**— Data source not found ## Disable permissions for a data source ``` POST /api/datasources/:id/disable-permissions ``` Disables permissions for the data source with the given id. All existing permissions are removed and anyone is able to query the data source. **Example request** ``` POST /api/datasources/1/disable-permissions Accept: application/json Content-Type: application/json Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk {} ``` **Example response** ``` HTTP/1.1 200 OK Content-Type: application/json; charset=UTF-8 Content-Length: 35 {"message":"Datasource permissions disabled"} ``` Status Codes: + **200**— Ok + **400**— Permissions can't be disabled, see the response body for details. + **401**— Unauthorized + **403**— Access denied + **404**— Data source not found ## Get permissions for a data source ``` GET /api/datasources/:id/permissions ``` Gets all existing permissions for the data source with the given `id`. **Example request** ``` GET /api/datasources/1/permissions HTTP/1.1 Accept: application/json Content-Type: application/json Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk ``` **Example response** ``` HTTP/1.1 200 OK Content-Type: application/json; charset=UTF-8 Content-Length: 551 { "datasourceId": 1, "enabled": true, "permissions": [ { "id": 1, "datasourceId": 1, "userId": 1, "userLogin": "user", "userEmail": "user@test.com", "userAvatarUrl": "/avatar/46d229b033af06a191ff2267bca9ae", "permission": 1, "permissionName": "Query", "created": "2017-06-20T02:00:00+02:00", "updated": "2017-06-20T02:00:00+02:00", }, { "id": 2, "datasourceId": 1, "teamId": 1, "team": "A Team", "teamAvatarUrl": "/avatar/46d229b033af06a191ff2267bca9ae", "permission": 1, "permissionName": "Query", "created": "2017-06-20T02:00:00+02:00", "updated": "2017-06-20T02:00:00+02:00", } ] } ``` Status Codes: + **200**— Ok + **401**— Unauthorized + **403**— Access denied + **404**— Data source not found ## Add permission for a data source ``` POST /api/datasources/:id/permissions ``` Adds a user permission for the data source with the given `id`. **Example request to add user permission** ``` POST /api/datasources/1/permissions Accept: application/json Content-Type: application/json Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk { "userId": 1, "permission": 1 } ``` **Example response for adding a user permission** ``` HTTP/1.1 200 OK Content-Type: application/json; charset=UTF-8 Content-Length: 35 {"message":"Datasource permission added"} ``` **Example request to add team permission** ``` POST /api/datasources/1/permissions Accept: application/json Content-Type: application/json Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk { "teamId": 1, "permission": 1 } ``` **Example response for adding a team permission** ``` HTTP/1.1 200 OK Content-Type: application/json; charset=UTF-8 Content-Length: 35 {"message":"Datasource permission added"} ``` Status Codes: + **200**— Ok + **400**— Permission can't be added, see response body for details. + **401**— Unauthorized + **403**— Access denied + **404**— Data source not found ## Remove permission for a data source ``` DELETE /api/datasources/:id/permissions/:permissionId ``` Removes the permission with the given permissionId for the data source with the given `id`. **Example request** ``` DELETE /api/datasources/1/permissions/2 Accept: application/json Content-Type: application/json Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk ``` **Example response** ``` HTTP/1.1 200 OK Content-Type: application/json; charset=UTF-8 Content-Length: 35 {"message":"Datasource permission removed"} ``` Status Codes: + **200**— Ok + **401**— Unauthorized + **403**— Access denied + **404**— Data source not found or permission not found # External Group Synchronization API **Note** To use a Grafana API with your Amazon Managed Grafana workspace, you must have a valid service account token. You include this in the `Authorization` field in the API request. ## Get external groups ``` GET /api/teams/:teamId/groups ``` **Example request** ``` GET /api/teams/1/groups HTTP/1.1 Accept: application/json Content-Type: application/json Authorization Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk] ``` **Example response** ``` HTTP/1.1 200 Content-Type: application/json [ { "orgId": 1, "teamId": 1, "groupId": "cn=editors,ou=groups,dc=grafana,dc=org" } ] ``` Status Codes: + **200**— Ok + **401**— Unauthorized + **403**— Access denied ## Add external group ``` POST /api/teams/:teamId/groups ``` **Example request** ``` POST /api/teams/1/members HTTP/1.1 Accept: application/json Content-Type: application/json Authorization Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk] { "groupId": "cn=editors,ou=groups,dc=grafana,dc=org" } ``` **Example response** ``` HTTP/1.1 200 Content-Type: application/json {"message":"Group added to Team"} ``` Status Codes: + **200**— Ok + **400**— Group is already added to this team + **401**— Unauthorized + **403**— Permission denied + **404**— Team not found ## Remove external group ``` DELETE /api/teams/:teamId/groups/:groupId ``` **Example request** ``` DELETE /api/teams/1/groups/cn=editors,ou=groups,dc=grafana,dc=org HTTP/1.1 Accept: application/json Content-Type: application/json Authorization Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk] ``` **Example response** ``` HTTP/1.1 200 Content-Type: application/json {"message":"Team Group removed"} ``` Status Codes: + **200**— Ok + **401**— Unauthorized + **403**— Permission denied + **404**— Team not found or group not found # Folder API Use the Folder API to work with folders in the Amazon Managed Grafana workspace. The identifier (id) of a folder is an auto-incrementing numeric value and is only unique per workspace. The unique identifier (uid) of a folder can be used to uniquely identify a folder between multiple workspaces. It’s automatically generated if you don't provide one when you create a folder. The uid allows having consistent URLs for accessing folder and when synchronizing folder between multiple Amazon Managed Grafana workspaces. The use of the uid means that changing the title of a folder does not break any bookmarked links to that folder. The uid can have a maximum length of 40 characters. Folders can't be nested. **Note** To use a Grafana API with your Amazon Managed Grafana workspace, you must have a valid service account token. You include this in the `Authorization` field in the API request. The **General** folder, with an `id` of 0, is not part of the Folder API. You can't use the Folder API to retrieve information about the general folder. ## Create folder ``` POST /api/folders ``` Creates a new folder. **Example request** ``` POST /api/folders HTTP/1.1 Accept: application/json Content-Type: application/json Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk { "uid": "nErXDvCkzz", "title": "Department ABC" } ``` JSON body schema: + **uid**— Optional unique identifer. If null, a new uid is generated. + **title**— The title for the folder. **Example response** ``` HTTP/1.1 200 Content-Type: application/json { "id":1, "uid": "nErXDvCkzz", "title": "Department ABC", "url": "/dashboards/f/nErXDvCkzz/department-abc", "hasAcl": false, "canSave": true, "canEdit": true, "canAdmin": true, "createdBy": "admin", "created": "2018-01-31T17:43:12+01:00", "updatedBy": "admin", "updated": "2018-01-31T17:43:12+01:00", "version": 1 } ``` Status Codes: + **200**— Created + **400**— Error such as invalid JSON, invalid or missing fields + **401**— Unauthorized + **403**— Access denied ## Update folder ``` PUT /api/folders/:uid ``` Updates the existing folder that matches the uid. **Example request** ``` PUT /api/folders/nErXDvCkzz HTTP/1.1 Accept: application/json Content-Type: application/json Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk { "title":"Department DEF", "version": 1 } ``` JSON body schema: + **uid**— Changes the unique identifer, if provided. + **title**— The title of the folder. + **version**— Provide the current version to be able to overwrite the folder. Not needed if `overwrite=true`. + **overwrite**— Set to `true` to overwrite the existing folder with a newer version. **Example response** ``` HTTP/1.1 200 Content-Type: application/json { "id":1, "uid": "nErXDvCkzz", "title": "Department DEF", "url": "/dashboards/f/nErXDvCkzz/department-def", "hasAcl": false, "canSave": true, "canEdit": true, "canAdmin": true, "createdBy": "admin", "created": "2018-01-31T17:43:12+01:00", "updatedBy": "admin", "updated": "2018-01-31T17:43:12+01:00", "version": 1 } ``` Status Codes: + **200**— Created + **400**— Error such as invalid JSON, invalid or missing fields + **401**— Unauthorized + **403**— Access denied + **404**— Folder not found + **412**— Precondition failed The **412** status code is used to explain why the folder can't be updated. + The folder has been changed by someone else `status=version-mismatch` The response body has the following properties: ``` HTTP/1.1 412 Precondition Failed Content-Type: application/json; charset=UTF-8 Content-Length: 97 { "message": "The folder has been changed by someone else", "status": "version-mismatch" } ``` ## Get all folders ``` GET /api/folders ``` Returns all folders that you have permission to view. You can control the maximum number of folders returned by using the `limit` query parameter. The default is 1000. **Example request** ``` GET /api/folders?limit=10 HTTP/1.1 Accept: application/json Content-Type: application/json Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk ``` **Example response** ``` HTTP/1.1 200 Content-Type: application/json [ { "id":1, "uid": "nErXDvCkzz", "title": "Department ABC" }, { "id":2, "uid": "k3S1cklGk", "title": "Department RND" } ] ``` ## Get folder by uid ``` GET /api/folders/:uid ``` Returns all folders that matches the given uid. **Example request** ``` GET /api/folders/nErXDvCkzzh HTTP/1.1 Accept: application/json Content-Type: application/json Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk ``` **Example response** ``` HTTP/1.1 200 Content-Type: application/json { "id":1, "uid": "nErXDvCkzz", "title": "Department ABC", "url": "/dashboards/f/nErXDvCkzz/department-abc", "hasAcl": false, "canSave": true, "canEdit": true, "canAdmin": true, "createdBy": "admin", "created": "2018-01-31T17:43:12+01:00", "updatedBy": "admin", "updated": "2018-01-31T17:43:12+01:00", "version": 1 } ``` Status Codes: + **200**— Found + **401**— Unauthorized + **403**— Access denied + **404**— Not found ## Get folder by id ``` GET /api/folders/id/:id ``` Returns the folder that matches the given id. **Example request** ``` GET /api/folders/id/1 HTTP/1.1 Accept: application/json Content-Type: application/json Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk ``` **Example response** ``` HTTP/1.1 200 Content-Type: application/json { "id":1, "uid": "nErXDvCkzz", "title": "Department ABC", "url": "/dashboards/f/nErXDvCkzz/department-abc", "hasAcl": false, "canSave": true, "canEdit": true, "canAdmin": true, "createdBy": "admin", "created": "2018-01-31T17:43:12+01:00", "updatedBy": "admin", "updated": "2018-01-31T17:43:12+01:00", "version": 1 } ``` Status Codes: + **200**— Found + **401**— Unauthorized + **403**— Access denied + **404**— Not found ## Delete folder by uid ``` DELETE /api/folders/:uid ``` Deletes the folder matching the uid, and also deletes all dashboards stored in the folder. This oepration can't be reverted. **Example request** ``` DELETE /api/folders/nErXDvCkzz HTTP/1.1 Accept: application/json Content-Type: application/json Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk ``` **Example response** ``` HTTP/1.1 200 Content-Type: application/json { "message":"Folder deleted", "id": 2 } ``` Status Codes: + **200**— Deleted + **401**— Unauthorized + **403**— Access denied + **404**— Not found # Folder/Dashboard Search API Use the FolderDashboard-Search API to search folders and dashboards in an Amazon Managed Grafana workspace. **Note** To use a Grafana API with your Amazon Managed Grafana workspace, you must have a valid service account token. You include this in the `Authorization` field in the API request. ## Search folders and dashboards ``` GET /api/search/ ``` Query parameters: + **query**— Search query + **tag**— List of tags to search for. These are Grafana tags, not AWS tags. + **type**— The type to search for, either `dash-folder` or `dash-db`. + **dashboardIds**— List of dashboard Id's to search for. + **folderIds**— List of dashboard Id's to search for in dashboards. + **starred**— Flag to specify that only starred dashboards are to be returned. + **limit**— Limit the number of returned results (maximum is 5000). + **page**— Use this parameter to access hits beyond limit. Numbering starts at 1. The `limit` parameter acts as page size. **Example request for retrieving folders and dashboards of the general folder** ``` GET /api/search?folderIds=0&query=&starred=false HTTP/1.1 Accept: application/json Content-Type: application/json Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk ``` **Example response for retrieving folders and dashboards of the general folder** ``` HTTP/1.1 200 Content-Type: application/json [ { "id": 163, "uid": "000000163", "title": "Folder", "url": "/dashboards/f/000000163/folder", "type": "dash-folder", "tags": [], "isStarred": false, "uri":"db/folder" // deprecated in Grafana v5.0 }, { "id":1, "uid": "cIBgcSjkk", "title":"Production Overview", "url": "/d/cIBgcSjkk/production-overview", "type":"dash-db", "tags":[prod], "isStarred":true, "uri":"db/production-overview" // deprecated in Grafana v5.0 } ] ``` **Example request for searching for starred dashboards** ``` GET /api/search?query=Production%20Overview&starred=true&tag=prod HTTP/1.1 Accept: application/json Content-Type: application/json Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk ``` **Example response for searching for starred dashboards** ``` HTTP/1.1 200 Content-Type: application/json [HTTP/1.1 200 Content-Type: application/json [ { "id":1, "uid": "cIBgcSjkk", "title":"Production Overview", "url": "/d/cIBgcSjkk/production-overview", "type":"dash-db", "tags":[prod], "isStarred":true, "folderId": 2, "folderUid": "000000163", "folderTitle": "Folder", "folderUrl": "/dashboards/f/000000163/folder", "uri":"db/production-overview" // deprecated in Grafana v5.0 } ] ``` # Folder Permissions API Use the Folder API to update or retrieve the permissions for a folder. Permissions with `folderId=-1` are the default permissions for users with the Viewer and Editor roles. Permissions can be set for a user, a team or a role (Viewer or Editor). Permissions cannot be set for Admins - they always have access to everything. The permission levels for the `permission` field are as follows: + 1 = View + 2 = Edit + 4 = Admin **Note** To use a Grafana API with your Amazon Managed Grafana workspace, you must have a valid service account token. You include this in the `Authorization` field in the API request. ## Get permissions for a folder ``` GET /api/folders/:uid/permissions ``` Gets all existing permissions for the folder with the given `uid`. **Example request** ``` GET /api/folders/nErXDvCkzz/permissions HTTP/1.1 Accept: application/json Content-Type: application/json Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk ``` **Example response** ``` HTTP/1.1 200 OK Content-Type: application/json; charset=UTF-8 Content-Length: 551 [ { "id": 1, "folderId": -1, "created": "2017-06-20T02:00:00+02:00", "updated": "2017-06-20T02:00:00+02:00", "userId": 0, "userLogin": "", "userEmail": "", "teamId": 0, "team": "", "role": "Viewer", "permission": 1, "permissionName": "View", "uid": "nErXDvCkzz", "title": "", "slug": "", "isFolder": false, "url": "" }, { "id": 2, "dashboardId": -1, "created": "2017-06-20T02:00:00+02:00", "updated": "2017-06-20T02:00:00+02:00", "userId": 0, "userLogin": "", "userEmail": "", "teamId": 0, "team": "", "role": "Editor", "permission": 2, "permissionName": "Edit", "uid": "", "title": "", "slug": "", "isFolder": false, "url": "" } ] ``` Status Codes: + **200**— OK + **401**— Unauthorized + **403**— Access denied + **404**— Folder not found ## Update permissions for a folder ``` POST /api/folders/:uid/permissions ``` Updates the permissions for a folder. This operation removes existing permissions if they are not included in the request. **Example request** ``` POST /api/folders/nErXDvCkzz/permissions Accept: application/json Content-Type: application/json Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk { "items": [ { "role": "Viewer", "permission": 1 }, { "role": "Editor", "permission": 2 }, { "teamId": 1, "permission": 1 }, { "userId": 11, "permission": 4 } ] } ``` JSON body schema: + **items**— The permission items to add or update. Existing items that are omitted from the list are removed. **Example response** ``` HTTP/1.1 200 OK Content-Type: application/json; charset=UTF-8 Content-Length: 35 {"message":"Folder permissions updated","id":1,"title":"Department ABC"} ``` Status Codes: + **200**— Created + **401**— Unauthorized + **403**— Access denied + **404**— Dashboard not found # Organization API Use the Organization API to work with organizations in an Amazon Managed Grafana workspace. **Note** To use a Grafana API with your Amazon Managed Grafana workspace, you must have a valid service account token. You include this in the `Authorization` field in the API request. ## Get current organization ``` GET /api/org/ ``` **Example request** ``` GET /api/org/ HTTP/1.1 Accept: application/json Content-Type: application/json Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk ``` **Example response** ``` HTTP/1.1 200 Content-Type: application/json { "id":1, "name":"Main Org." } ``` ## Get all users within the current organization ``` GET /api/org/users ``` Required permissions: the `org.users:read` action with the scope `users:*` **Example request** ``` GET /api/org/users HTTP/1.1 Accept: application/json Content-Type: application/json Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk ``` **Example response** ``` HTTP/1.1 200 Content-Type: application/json [ { "orgId": 1, "userId": 1, "email": "admin@localhost", "avatarUrl": "/avatar/46d229b033af06a191ff2267bca9ae", "login": "admin", "role": "Admin", "lastSeenAt": "2019-08-09T11:02:49+02:00", "lastSeenAtAge": "< 1m" } ] ``` ## Get all users within the current organization (lookup) ``` GET /api/org/users/lookup ``` Returns all users within the current organization, but with less detailed information. Accessible to users with org admin role, admin in any folder or admin of any team. Used mostly by the Grafana UI to provide a list of users when adding team members and when e diting folder/dashboard permissions. **Example request** ``` GET /api/org/users/lookup HTTP/1.1 Accept: application/json Content-Type: application/json Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk ``` **Example response** ``` HTTP/1.1 200 Content-Type: application/json [ { "userId": 1, "login": "admin", "avatarUrl": "/avatar/46d229b033af06a191ff2267bca9ae" } ] ``` ## Updates the given user ``` PATCH /api/org/users/:userId ``` Required permissions: the `org.users.role:update` action with the scope `users:*` **Example request** ``` PATCH /api/org/users/1 HTTP/1.1 Accept: application/json Content-Type: application/json Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk { "role": "Viewer", } ``` **Example response** ``` HTTP/1.1 200 Content-Type: application/json {"message":"Organization user updated"} ``` ## Deletes user in current organization ``` DELETE /api/org/users/:userId ``` Required permissions: the `org.users:remove` action with the scope `users:*` **Example request** ``` DELETE /api/org/users/1 HTTP/1.1 Accept: application/json Content-Type: application/json Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk ``` **Example response** ``` HTTP/1.1 200 Content-Type: application/json {"message":"User removed from organization"} ``` ## Update the current organization ``` PUT /api/org ``` **Example request** ``` PUT /api/org HTTP/1.1 Accept: application/json Content-Type: application/json Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk { "name":"Main Org." } ``` **Example response** ``` HTTP/1.1 200 Content-Type: application/json {"message":"Organization updated"} ``` ## Add user to the current organization ``` POST /api/org/users ``` Required permissions: the `org.users:add` action with the scope `users:*` **Example request** ``` POST /api/org/users HTTP/1.1 Accept: application/json Content-Type: application/json Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk { "role": "Admin", "loginOrEmail": "admin" } ``` **Example response** ``` HTTP/1.1 200 Content-Type: application/json {"message":"User added to organization","userId":1} ``` # Playlist API Use the Playlist API to work with playlists in the Amazon Managed Grafana workspace. **Note** To use a Grafana API with your Amazon Managed Grafana workspace, you must have a valid service account token. You include this in the `Authorization` field in the API request. ## List playlists ``` GET /apis/playlist.grafana.app/v1/namespaces/default/playlists ``` Lists all playlists in the workspace. **Example request** ``` GET /apis/playlist.grafana.app/v1/namespaces/default/playlists HTTP/1.1 Accept: application/json Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk ``` **Example response** ``` HTTP/1.1 200 Content-Type: application/json { "kind": "PlaylistList", "apiVersion": "playlist.grafana.app/v1", "metadata": {}, "items": [ { "kind": "Playlist", "apiVersion": "playlist.grafana.app/v1", "metadata": { "name": "my-playlist-uid", "namespace": "default" }, "spec": { "title": "My Playlist", "interval": "5m", "items": [ {"type": "dashboard_by_uid", "value": "dashboard-uid-1"} ] } } ] } ``` ## Get a playlist ``` GET /apis/playlist.grafana.app/v1/namespaces/default/playlists/:name ``` Retrieves a specific playlist by name (UID). **Example request** ``` GET /apis/playlist.grafana.app/v1/namespaces/default/playlists/my-playlist-uid HTTP/1.1 Accept: application/json Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk ``` **Example response** ``` HTTP/1.1 200 Content-Type: application/json { "kind": "Playlist", "apiVersion": "playlist.grafana.app/v1", "metadata": { "name": "my-playlist-uid", "namespace": "default" }, "spec": { "title": "My Playlist", "interval": "5m", "items": [ {"type": "dashboard_by_uid", "value": "dashboard-uid-1"} ] } } ``` ## Create a playlist ``` POST /apis/playlist.grafana.app/v1/namespaces/default/playlists ``` Creates a new playlist. **Example request** ``` POST /apis/playlist.grafana.app/v1/namespaces/default/playlists HTTP/1.1 Accept: application/json Content-Type: application/json Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk { "metadata": {"name": "my-new-playlist-uid"}, "spec": { "title": "My New Playlist", "interval": "5m", "items": [ {"type": "dashboard_by_uid", "value": "dashboard-uid-1"} ] } } ``` ## Update a playlist ``` PUT /apis/playlist.grafana.app/v1/namespaces/default/playlists/:name ``` Updates an existing playlist. The entire playlist spec must be provided. **Example request** ``` PUT /apis/playlist.grafana.app/v1/namespaces/default/playlists/my-playlist-uid HTTP/1.1 Accept: application/json Content-Type: application/json Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk { "metadata": { "name": "my-playlist-uid", "resourceVersion": "1234567890" }, "spec": { "title": "Updated Playlist", "interval": "10m", "items": [ {"type": "dashboard_by_uid", "value": "dashboard-uid-1"}, {"type": "dashboard_by_tag", "value": "monitoring"} ] } } ``` ## Delete a playlist ``` DELETE /apis/playlist.grafana.app/v1/namespaces/default/playlists/:name ``` Deletes a playlist by name (UID). **Example request** ``` DELETE /apis/playlist.grafana.app/v1/namespaces/default/playlists/my-playlist-uid HTTP/1.1 Accept: application/json Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk ``` **Example response** ``` HTTP/1.1 200 Content-Type: application/json { "kind": "Status", "apiVersion": "v1", "status": "Success", "code": 200 } ``` ## Search playlist (deprecated) **Important** This endpoint is deprecated. Use [List playlists](#v12-Grafana-API-Playlist-list) instead. ``` GET /api/playlists ``` Returns all playlists for the current Amazon Managed Grafana workspace, using pagination. **Example request** ``` GET /api/playlists HTTP/1.1 Accept: application/json Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk ``` Querystring parameters: + **query**— Limit the responses to playlists that have a name like this value. + **limit**— Limit the response to X number of playlists. **Example response** ``` HTTP/1.1 200 Content-Type: application/json [ { "id": 1, "name": "my playlist", "interval": "5m" } ] ``` ## Get one playlist (deprecated) **Important** This endpoint is deprecated. Use [Get a playlist](#v12-Grafana-API-Playlist-get) instead. ``` GET /api/playlists/:id ``` **Example request** ``` GET /api/playlists/1 HTTP/1.1 Accept: application/json Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk ``` **Example response** ``` HTTP/1.1 200 Content-Type: application/json { "id" : 1, "name": "my playlist", "interval": "5m", "orgId": "my org", "items": [ { "id": 1, "playlistId": 1, "type": "dashboard_by_id", "value": "3", "order": 1, "title":"my third dashboard" }, { "id": 2, "playlistId": 1, "type": "dashboard_by_tag", "value": "myTag", "order": 2, "title":"my other dashboard" } ] } ``` ## Get playlist items (deprecated) **Important** This endpoint is deprecated. Use [Get a playlist](#v12-Grafana-API-Playlist-get) instead. Playlist items are included in the playlist response. ``` GET /api/playlists/:id/items ``` **Example request** ``` GET /api/playlists/1/items HTTP/1.1 Accept: application/json Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk ``` **Example response** ``` HTTP/1.1 200 Content-Type: application/json [ { "id": 1, "playlistId": 1, "type": "dashboard_by_id", "value": "3", "order": 1, "title":"my third dashboard" }, { "id": 2, "playlistId": 1, "type": "dashboard_by_tag", "value": "myTag", "order": 2, "title":"my other dashboard" } ] ``` ## Get playlist dashboards (deprecated) **Important** This endpoint is deprecated. Use [Get a playlist](#v12-Grafana-API-Playlist-get) instead. ``` GET /api/playlists/:id/dashboards ``` **Example request** ``` GET /api/playlists/1/dashboards HTTP/1.1 Accept: application/json Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk ``` **Example response** ``` HTTP/1.1 200 Content-Type: application/json [ { "id": 3, "title": "my third dashboard", "order": 1, }, { "id": 5, "title":"my other dashboard" "order": 2, } ] ``` ## Create a playlist (deprecated) **Important** This endpoint is deprecated. Use [Create a playlist](#v12-Grafana-API-Playlist-create) instead. ``` POST /api/playlists/ ``` **Example request** ``` PUT /api/playlists/1 HTTP/1.1 Accept: application/json Content-Type: application/json Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk { "name": "my playlist", "interval": "5m", "items": [ { "type": "dashboard_by_id", "value": "3", "order": 1, "title":"my third dashboard" }, { "type": "dashboard_by_tag", "value": "myTag", "order": 2, "title":"my other dashboard" } ] } ``` **Example response** ``` HTTP/1.1 200 Content-Type: application/json { "id": 1, "name": "my playlist", "interval": "5m" } ``` ## Update a playlist (deprecated) **Important** This endpoint is deprecated. Use [Update a playlist](#v12-Grafana-API-Playlist-update) instead. ``` PUT /api/playlists/:id ``` **Example request** ``` PUT /api/playlists/1 HTTP/1.1 Accept: application/json Content-Type: application/json Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk { "name": "my playlist", "interval": "5m", "items": [ { "playlistId": 1, "type": "dashboard_by_id", "value": "3", "order": 1, "title":"my third dashboard" }, { "playlistId": 1, "type": "dashboard_by_tag", "value": "myTag", "order": 2, "title":"my other dashboard" } ] } ``` **Example response** ``` HTTP/1.1 200 Content-Type: application/json { "id" : 1, "name": "my playlist", "interval": "5m", "orgId": "my org", "items": [ { "id": 1, "playlistId": 1, "type": "dashboard_by_id", "value": "3", "order": 1, "title":"my third dashboard" }, { "id": 2, "playlistId": 1, "type": "dashboard_by_tag", "value": "myTag", "order": 2, "title":"my other dashboard" } ] } ``` ## Delete a playlist (deprecated) **Important** This endpoint is deprecated. Use [Delete a playlist](#v12-Grafana-API-Playlist-delete) instead. ``` DELETE /api/playlists/:id ``` **Example request** ``` DELETE /api/playlists/1 HTTP/1.1 Accept: application/json Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk ``` **Example response** ``` HTTP/1.1 200 Content-Type: application/json {} ``` # Plugin API Use the Plugin API to manage plugins in the Amazon Managed Grafana workspace. To make changes to plugins with this API, the workspace must have [plugin management enabled](AMG-configure-workspace.md) for your workspace. The user defined by the service account token must also be an [admin](Grafana-user-roles.md) for the Amazon Managed Grafana workspace. **Note** To use a Grafana API with your Amazon Managed Grafana workspace, you must have a valid service account token. You include this in the `Authorization` field in the API request. ## Install plugin ``` POST /api/plugins/:id/install ``` **Example request** ``` POST /api/plugins/grafana-athena-datasource/install HTTP/1.1 Accept: application/json Content-Type: application/json Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk { "version": "2.12.0" # optional, uses the latest compatible version if not provided } ``` **Example response** ``` HTTP/1.1 200 ``` ## Uninstall plugin ``` POST /api/plugins/:id/uninstall ``` **Example request** ``` POST /api/plugins/grafana-athena-datasource/uninstall HTTP/1.1 Accept: application/json Content-Type: application/json Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk { "version": "2.12.0" # optional, uninstalls whatever is installed if not provided } ``` **Example response** ``` HTTP/1.1 200 ``` ## Get all plugins ``` GET /api/gnet/plugins ``` **Example request** ``` GET /api/gnet/plugins HTTP/1.1 Accept: application/json Content-Type: application/json Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk ``` **Example response** ``` HTTP/1.1 200 Content-Type: application/json { "items": [ { "status": "active", "id": 74, "typeId": 1, "typeName": "Application", "typeCode": "app", "slug": "alexanderzobnin-zabbix-app", "name": "Zabbix", "description": "Zabbix plugin for Grafana", "version": "4.4.3", "versionStatus": "active", "versionSignatureType": "grafana", "versionSignedByOrg": "grafana", "versionSignedByOrgName": "Grafana Labs", "userId": 0, "orgId": 13056, "orgName": "Alexander Zobnin", "orgSlug": "alexanderzobnin", "orgUrl": "https://github.com/alexanderzobnin", "url": "https://github.com/grafana/grafana-zabbix/", "createdAt": "2016-04-06T20:23:41.000Z", "updatedAt": "2023-10-10T12:53:51.000Z", "downloads": 90788771, "verified": false, "featured": 180, "internal": false, "downloadSlug": "alexanderzobnin-zabbix-app", "popularity": 0.2485, "signatureType": "grafana", "packages": { "linux-amd64": { "md5": "baa06e8f26731f99748c58522cd4ffb6", "sha256": "a4a108f2e04a2114810c7b60419b4b04bf80d3377e2394b0586e2dc96b5a929c", "packageName": "linux-amd64", "downloadUrl": "/api/plugins/alexanderzobnin-zabbix-app/versions/4.4.3/download?os=linux&arch=amd64" }, <... further packages> }, "links": [ { "rel": "self", "href": "/plugins/alexanderzobnin-zabbix-app" }, <... further links> ], "angularDetected": false }, <... further plugins> ], "orderBy": "weight", "direction": "asc", "links": [ { "rel": "self", "href": "/plugins" } ] } ``` ## Get plugin ``` GET /api/gnet/plugins/:id ``` **Example request** ``` GET /api/gnet/plugins/grafana-athena-datasource HTTP/1.1 Accept: application/json Content-Type: application/json Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk ``` **Example response** ``` HTTP/1.1 200 Content-Type: application/json { "status": "active", "id": 764, "typeId": 2, "typeName": "Data Source", "typeCode": "datasource", "slug": "grafana-athena-datasource", "name": "Amazon Athena", "description": "Use Amazon Athena with Grafana", "version": "2.13.0", "versionStatus": "active", "versionSignatureType": "grafana", "versionSignedByOrg": "grafana", "versionSignedByOrgName": "Grafana Labs", "userId": 0, "orgId": 5000, "orgName": "Grafana Labs", "orgSlug": "grafana", "orgUrl": "https://grafana.org", "url": "https://github.com/grafana/athena-datasource/", "createdAt": "2021-11-24T08:55:41.000Z", "updatedAt": "2023-10-31T17:20:32.000Z", "json": { "$schema": "https://raw.githubusercontent.com/grafana/grafana/master/docs/sources/developers/plugins/plugin.schema.json", "alerting": true, "annotations": true, "backend": true, "dependencies": { "grafanaDependency": ">=8.0.0", "plugins": [] }, "executable": "gpx_athena", "id": "grafana-athena-datasource", "includes": [ { "name": "Cost Usage Report Monitoring", "path": "dashboards/cur-monitoring.json", "type": "dashboard" }, { "name": "Amazon VPC Flow Logs", "path": "dashboards/vpc-flow-logs.json", "type": "dashboard" } ], "info": { "author": { "name": "Grafana Labs", "url": "https://grafana.com" }, "build": { "time": 1698764559022, "repo": "https://github.com/grafana/athena-datasource", "branch": "main", "hash": "25cc131300f1ed22593bc3ba08b2bef7d23fbcd01", "build": 1462 }, "description": "Use Amazon Athena with Grafana", "keywords": [ "datasource", "athena" ], "links": [ { "name": "Website", "url": "https://github.com/grafana/athena-datasource" }, { "name": "License", "url": "https://github.com/grafana/athena-datasource/blob/master/LICENSE" } ], "logos": { "large": "img/logo.svg", "small": "img/logo.svg" }, "screenshots": [], "updated": "2023-10-31", "version": "2.13.0" }, "metrics": true, "name": "Amazon Athena", "type": "datasource" }, "readme": "<... full HTML readme>", "statusContext": "", "downloads": 2505825, "verified": false, "featured": 0, "internal": false, "downloadSlug": "grafana-athena-datasource", "popularity": 0.0594, "signatureType": "grafana", "grafanaDependency": ">=8.0.0", "packages": { "linux-amd64": { "md5": "7efef359bf917b4ca6b149de42a1282d", "sha256": "cd2fc5737c321dc3d8bbe2852c801c01adb64eacc9f60420bd21dc18bee43531", "packageName": "linux-amd64", "downloadUrl": "/api/plugins/grafana-athena-datasource/versions/2.13.0/download?os=linux&arch=amd64" }, <... other packages> }, "links": [ { "rel": "self", "href": "/plugins/grafana-athena-datasource" }, <... other links> ], "angularDetected": false } ``` ## Get plugin versions ``` POST /api/gnet/plugins/:id/versions ``` **Example request** ``` GET /api/gnet/plugins/grafana-athena-datasource/versions HTTP/1.1 Accept: application/json Content-Type: application/json Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk ``` **Example response** ``` HTTP/1.1 200 Content-Type: application/json { "items": [ { "id": 5306, "pluginId": 764, "pluginSlug": "grafana-athena-datasource", "version": "2.13.0", "url": "https://github.com/grafana/athena-datasource/", "commit": "", "description": "Use Amazon Athena with Grafana", "createdAt": "2023-10-31T17:20:31.000Z", "updatedAt": null, "downloads": 33790, "verified": false, "status": "active", "statusContext": "", "downloadSlug": "grafana-athena-datasource", "packages": {}, "links": [ { "rel": "self", "href": "/plugins/grafana-athena-datasource/versions/2.13.0" }, { "rel": "images", "href": "/plugins/grafana-athena-datasource/versions/2.13.0/images" }, { "rel": "thumbnails", "href": "/plugins/grafana-athena-datasource/versions/2.13.0/thumbnails" }, { "rel": "plugin", "href": "/plugins/grafana-athena-datasource" }, { "rel": "download", "href": "/plugins/grafana-athena-datasource/versions/2.13.0/download" } ], "grafanaDependency": ">=8.0.0", "angularDetected": false }, { "id": 5244, "pluginId": 764, "pluginSlug": "grafana-athena-datasource", "version": "2.12.0", "url": "https://github.com/grafana/athena-datasource/", "commit": "", "description": "Use Amazon Athena with Grafana", "createdAt": "2023-10-17T12:42:13.000Z", "updatedAt": null, "downloads": 60742, "verified": false, "status": "active", "statusContext": "", "downloadSlug": "grafana-athena-datasource", "packages": {}, "links": [ { "rel": "self", "href": "/plugins/grafana-athena-datasource/versions/2.12.0" }, { "rel": "images", "href": "/plugins/grafana-athena-datasource/versions/2.12.0/images" }, { "rel": "thumbnails", "href": "/plugins/grafana-athena-datasource/versions/2.12.0/thumbnails" }, { "rel": "plugin", "href": "/plugins/grafana-athena-datasource" }, { "rel": "download", "href": "/plugins/grafana-athena-datasource/versions/2.12.0/download" } ], "grafanaDependency": ">=8.0.0", "angularDetected": false }, <... other versions> ] } ``` # Preferences API Use the Preferences API to work with user preferences in the Amazon Managed Grafana workspace. Keys: + **theme**— Valid values are `light`, `dark`, or an empty string to use the default theme. + **homeDashboardId**— The numerical `:id` of a favorited dashboard. The default is 0. + **timezone**— Valid values are `utc`, `browser`, or an empty string to use the default. Omitting a key causes the current value to be replaced with the system default value. **Note** To use a Grafana API with your Amazon Managed Grafana workspace, you must have a valid service account token. You include this in the `Authorization` field in the API request. ## Get current user preferences ``` GET /api/user/preferences ``` **Example request** ``` GET /api/user/preferences HTTP/1.1 Accept: application/json Content-Type: application/json Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk ``` **Example response** ``` HTTP/1.1 200 Content-Type: application/json {"theme":"","homeDashboardId":0,"timezone":""} ``` ## Update current user preferences ``` PUT /api/user/preferences ``` **Example request** ``` PUT /api/user/preferences HTTP/1.1 Accept: application/json Content-Type: application/json Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk { "theme": "", "homeDashboardId":0, "timezone":"utc" } ``` **Example response** ``` HTTP/1.1 200 Content-Type: text/plain; charset=utf-8 {"message":"Preferences updated"} ``` ## Get current org preferences ``` GET /api/org/preferences ``` **Example request** ``` GET /api/org/preferences HTTP/1.1 Accept: application/json Content-Type: application/json Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk ``` **Example response** ``` HTTP/1.1 200 Content-Type: application/json {"theme":"","homeDashboardId":0,"timezone":""} ``` ## Update current org preferences ``` PUT /api/org/preferences ``` **Example request** ``` PUT /api/org/preferences HTTP/1.1 Accept: application/json Content-Type: application/json Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk { "theme": "", "homeDashboardId":0, "timezone":"utc" } ``` **Example response** ``` HTTP/1.1 200 Content-Type: text/plain; charset=utf-8 {"message":"Preferences updated"} ``` # Snapshot API Use the Snapshot API to work with snapshots in an Amazon Managed Grafana workspace. **Note** To use a Grafana API with your Amazon Managed Grafana workspace, you must have a valid service account token. You include this in the `Authorization` field in the API request. ## Create new shapshot ``` POST /api/snapshots ``` **Example request** ``` POST /api/snapshots HTTP/1.1 Accept: application/json Content-Type: application/json Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk { "dashboard": { "editable":false, "hideControls":true, "nav":[ { "enable":false, "type":"timepicker" } ], "rows": [ { } ], "style":"dark", "tags":[], "templating":{ "list":[ ] }, "time":{ }, "timezone":"browser", "title":"Home", "version":5 }, "expires": 3600 } ``` JSON body schema: + **dashboard**— (Required) The complete dashboard model. + **name**— (Optional) A name for the snapshot. + **expires**— (Optional) When the snapshot should expire, in seconds. The default is to never expire. + **external**— (Optional) Save the snapshot on an external server rather than locally. Default is false. + **key**— (Required if `external` is `true`) Define a unique key. + **deletekey**— (Required if `external` is `true`) A unique key to be used to delete the snapshot. It is different than `key` so that only the creator can delete the snapshot. **Note** When creating a snapshot using the API, you have to provide the full dashboard payload including the snapshot data. This endpoint is designed for the Grafana UI. **Example response** ``` HTTP/1.1 200 Content-Type: application/json { "deleteKey":"XXXXXXX", "deleteUrl":"myurl/api/snapshots-delete/XXXXXXX", "key":"YYYYYYY", "url":"myurl/dashboard/snapshot/YYYYYYY", "id": 1, } ``` Keys: + **deleteKey**— A key generated to be used to delete the snapshot. + **key**— A key generated to share the dashboard. ## Get list of snapshots ``` GET /api/dashboard/snapshots ``` Query parameters: + **query**— Search query + **limit**— Limit the number of returned results **Example request** ``` GET /api/dashboard/snapshots HTTP/1.1 Accept: application/json Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk ``` **Example response** ``` HTTP/1.1 200 Content-Type: application/json [ { "id":8, "name":"Home", "key":"YYYYYYY", "orgId":1, "userId":1, "external":false, "externalUrl":"", "expires":"2200-13-32T25:23:23+02:00", "created":"2200-13-32T28:24:23+02:00", "updated":"2200-13-32T28:24:23+02:00" } ] ``` ## Get snapshot by key ``` GET /api/snapshots/:key ``` **Example request** ``` GET /api/snapshots/YYYYYYY HTTP/1.1 Accept: application/json Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk ``` **Example response** ``` HTTP/1.1 200 Content-Type: application/json { "meta":{ "isSnapshot":true, "type":"snapshot", "canSave":false, "canEdit":false, "canStar":false, "slug":"", "expires":"2200-13-32T25:23:23+02:00", "created":"2200-13-32T28:24:23+02:00" }, "dashboard": { "editable":false, "hideControls":true, "nav": [ { "enable":false, "type":"timepicker" } ], "rows": [ { } ], "style":"dark", "tags":[], "templating":{ "list":[ ] }, "time":{ }, "timezone":"browser", "title":"Home", "version":5 } } ``` ## Delete snapshot by key ``` DELETE /api/snapshots/:key ``` **Example request** ``` DELETE /api/snapshots/YYYYYYY HTTP/1.1 Accept: application/json Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk ``` **Example response** ``` HTTP/1.1 200 Content-Type: application/json {"message":"Snapshot deleted. It might take an hour before it's cleared from any CDN caches.", "id": 1} ``` ## Delete snapshot by deleteKey This API call can be used without authentication by using the secret delete key for the snapshot. ``` GET /api/snapshots-delete/:deleteKey ``` **Example request** ``` GET /api/snapshots-delete/XXXXXXX HTTP/1.1 Accept: application/json ``` **Example response** ``` HTTP/1.1 200 Content-Type: application/json {"message":"Snapshot deleted. It might take an hour before it's cleared from any CDN caches.", "id": 1} ``` # Short URL API Use the Short URL API to create shortened URLs. A short URL represents a longer URL containing complex query parameters in a smaller and simpler format. **Note** To use a Grafana API with your Amazon Managed Grafana workspace, you must have a valid service account token. You include this in the `Authorization` field in the API request. ## Create short URL ``` POST /api/short-urls ``` Creates a short URL. **Example request** ``` POST /api/short-urls HTTP/1.1 Accept: application/json Content-Type: application/json Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk { "path": "d/TxKARsmGz/new-dashboard?orgId=1&from=1599389322894&to=1599410922894" } ``` JSON body schema: + **path** – The path to shorten, relative to the Grafana root URL. **Example response** ``` HTTP/1.1 200 Content-Type: application/json { "uid": "AT76wBvGk", "url": "/goto/AT76wBvGk?orgId=1" } ``` Status codes: + **200** – Created + **400** – Errors (invalid JSON, missing or invalid fields) ## Get short URL ``` GET /api/short-urls/:uid ``` Retrieves a short URL by its UID. **Example request** ``` GET /api/short-urls/AT76wBvGk HTTP/1.1 Accept: application/json Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk ``` **Example response** ``` HTTP/1.1 200 Content-Type: application/json { "uid": "AT76wBvGk", "path": "d/TxKARsmGz/new-dashboard?orgId=1&from=1599389322894&to=1599410922894" } ``` # Team API Use the Team API to work with teams in an Amazon Managed Grafana workspace. All actions in this API require that you have the Admin role. **Note** To use a Grafana API with your Amazon Managed Grafana workspace, you must have a valid service account token. You include this in the `Authorization` field in the API request. ## Team search with pagination ``` GET /api/teams/search?perpage=50&page=1&query=myteam ``` or ``` GET /api/teams/search?name=myteam ``` **Example request** ``` GET /api/teams/search?perpage=10&page=1&query=myteam HTTP/1.1 Accept: application/json Content-Type: application/json Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk ``` **Using the query parameter** The default value for the `perpage` parameter is 1000 and for the `page` parameter is 1. The `totalCount` field in the response can be used for pagination of the teams list. For example, if `totalCount` is 100 teams and the`perpage` parameter is set to 10, then there are 10 pages of teams. The `query` parameter is optional and returns results where the query value is contained in the `name` field. Query values with spaces need to be URL-encoded. For example, `query=my%20team`. **Using the name parameter** The `name` parameter returns a single team if the parameter matches the `name` field. **Example response** ``` HTTP/1.1 200 Content-Type: application/json { "totalCount": 1, "teams": [ { "id": 1, "orgId": 1, "name": "MyTestTeam", "email": "", "avatarUrl": "\/avatar\/3f49c15916554246daa714b9bd0ee39", "memberCount": 1 } ], "page": 1, "perPage": 1000 ``` Status Codes: + **200**— Created + **401**— Unauthorized + **403**— Permission denied + **404**— Team not found (if searching by name) ## Get team by Id ``` GET /api/teams/:id ``` **Example request** ``` GET /api/teams/1 HTTP/1.1 Accept: application/json Content-Type: application/json Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk ``` **Example response** ``` HHTTP/1.1 200 Content-Type: application/json { "id": 1, "orgId": 1, "name": "MyTestTeam", "email": "", "created": "2017-12-15T10:40:45+01:00", "updated": "2017-12-15T10:40:45+01:00" } ``` ## Add a team The `name` of the team must be unique. The `name` field is required and the `email` and `orgId` fields are optional. ``` POST /api/teams ``` **Example request** ``` POST /api/teams HTTP/1.1 Accept: application/json Content-Type: application/json Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk { "name": "MyTestTeam", "email": "email@test.com", "orgId": 2 } ``` **Example response** ``` HTTP/1.1 200 Content-Type: application/json {"message":"Team created","teamId":2} ``` Status Codes: + **200**— Created + **401**— Unauthorized + **403**— Permission denied + **409**— Team name already exists ## Update team ``` PUT /api/teams/:id ``` Only the `name` and `email` fields can be updated. **Example request** ``` PUT /api/teams/2 HTTP/1.1 Accept: application/json Content-Type: application/json Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk { "name": "MyTestTeam", "email": "email@test.com" } ``` **Example response** ``` HTTP/1.1 200 Content-Type: application/json {"message":"Team updated"} ``` Status Codes: + **200**— Created + **401**— Unauthorized + **403**— Permission denied + **404**— Team not found + **409**— Team name already exists ## Delete team by Id ``` DELETE /api/teams/:id ``` **Example request** ``` DELETE /api/teams/2 HTTP/1.1 Accept: application/json Content-Type: application/json Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk ``` **Example response** ``` HTTP/1.1 200 Content-Type: application/json {"message":"Team deleted"} ``` Status Codes: + **200**— Created + **401**— Unauthorized + **403**— Permission denied + **404**— Team not found ## Get team members ``` GET /api/teams/:teamId/members ``` **Example request** ``` GET /api/teams/1/members HTTP/1.1 Accept: application/json Content-Type: application/json Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk ``` **Example response** ``` HTTP/1.1 200 Content-Type: application/json [ { "orgId": 1, "teamId": 1, "userId": 3, "email": "user1@email.com", "login": "user1", "avatarUrl": "\/avatar\/1b3c32f6386b0185c40d359cdc733a7" }, { "orgId": 1, "teamId": 1, "userId": 2, "email": "user2@email.com", "login": "user2", "avatarUrl": "\/avatar\/cad3c68da76e45d10269e8ef02f8e7" } ] ``` Status Codes: + **200**— Created + **401**— Unauthorized + **403**— Permission denied ## Add team member ``` POST /api/teams/:teamId/members ``` **Example request** ``` POST /api/teams/1/members HTTP/1.1 Accept: application/json Content-Type: application/json Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk { "userId": 2 } ``` **Example response** ``` HTTP/1.1 200 Content-Type: application/json {"message":"Member added to Team"} ``` Status Codes: + **200**— Created + **400**— User is already in team + **401**— Unauthorized + **403**— Permission denied + **404**— Team not found ## Remove member from team ``` DELETE /api/teams/:teamId/members/:userId ``` **Example request** ``` DELETE /api/teams/2/members/3 HTTP/1.1 Accept: application/json Content-Type: application/json Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk ``` **Example response** ``` HTTP/1.1 200 Content-Type: application/json {"message":"Team Member removed"} ``` Status Codes: + **200**— Created + **401**— Unauthorized + **403**— Permission denied + **404**— Team not found/team member not found ## Get team preferences ``` GET /api/teams/:teamId/preferences ``` **Example request** ``` GET /api/teams/2/preferences HTTP/1.1 Accept: application/json Content-Type: application/json Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk ``` **Example response** ``` HTTP/1.1 200 Content-Type: application/json { "theme": "", "homeDashboardId": 0, "timezone": "" } ``` ## Update team preferences ``` PUT /api/teams/:teamId/preferences ``` **Example request** ``` PUT /api/teams/2/preferences HTTP/1.1 Accept: application/json Content-Type: application/json Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk { "theme": "dark", "homeDashboardId": 39, "timezone": "utc" } ``` JSON body schema: + **theme**— Specify either `light`, `dark`, or an empty string to use the default theme. + **homeDashboardId**— The numerical `:id` of a dashboard. The default is 0. + **timezone**— Specify either `utc`, `browser`, or an empty string to use the default. Omitting a parameter causes the current value to be replaced with the system default value. **Example response** ``` HTTP/1.1 200 Content-Type: text/plain; charset=utf-8 { "message":"Preferences updated" } ``` # User API Use the User API to work with users in an Amazon Managed Grafana workspace. **Note** To use a Grafana API with your Amazon Managed Grafana workspace, you must have a valid service account token. You include this in the `Authorization` field in the API request. ## Get teams that the user is a member of ``` GET /api/user/teams ``` **Example request** ``` GET /api/user/teams HTTP/1.1 Accept: application/json Content-Type: application/json Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk ``` **Example response** ``` HTTP/1.1 200 Content-Type: application/json [ { "id": 1, "orgId": 1, "name": "MyTestTeam", "email": "", "avatarUrl": "\/avatar\/3f49c15916554246daa714b9bd0ee3", "memberCount": 1 } ] ``` ## Get list of snapshots Stars the given Dashboard for the actual user. ``` POST /api/user/stars/dashboard/:dashboardId ``` **Example request** ``` POST /api/user/stars/dashboard/1 HTTP/1.1 Accept: application/json Content-Type: application/json Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk ``` **Example response** ``` HTTP/1.1 200 Content-Type: application/json {"message":"Dashboard starred!"} ``` ## Unstar a dashboard Deletes the starring of the given Dashboard for the actual user. ``` DELETE /api/user/stars/dashboard/:dashboardId ``` **Example request** ``` DELETE /api/user/stars/dashboard/1 HTTP/1.1 Accept: application/json Content-Type: application/json Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk ``` **Example response** ``` HTTP/1.1 200 Content-Type: application/json {"message":"Dashboard unstarred"} ``` ## Get auth tokens of the actual user ``` GET /api/user/auth-tokens ``` **Example request** ``` GET /api/user/auth-tokens HTTP/1.1 Accept: application/json Content-Type: application/json Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk ``` **Example response** ``` HTTP/1.1 200 Content-Type: application/json [ { "id": 361, "isActive": true, "clientIp": "127.0.0.1", "browser": "Chrome", "browserVersion": "72.0", "os": "Linux", "osVersion": "", "device": "Other", "createdAt": "2019-03-05T21:22:54+01:00", "seenAt": "2019-03-06T19:41:06+01:00" }, { "id": 364, "isActive": false, "clientIp": "127.0.0.1", "browser": "Mobile Safari", "browserVersion": "11.0", "os": "iOS", "osVersion": "11.0", "device": "iPhone", "createdAt": "2019-03-06T19:41:19+01:00", "seenAt": "2019-03-06T19:41:21+01:00" } ] ``` ## Revoke an auth token of the actual user ``` POST /api/user/revoke-auth-token ``` Revokes the given auth token (device) for the actual user. User of issued auth token (device) are no longer logged in and are required to authenticate again at their next activity. **Example request** ``` POST /api/user/revoke-auth-token HTTP/1.1 Accept: application/json Content-Type: application/json Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk { "authTokenId": 364 } ``` **Example response** ``` HTTP/1.1 200 Content-Type: application/json { "message": "User auth token revoked" } ```