[release-12.3.0] Restructure As code and developer resources (#113969)
Co-authored-by: Roberto Jiménez Sánchez <roberto.jimenez@grafana.com> Co-authored-by: Anna Urbiztondo <anna.urbiztondo@grafana.com>
This commit is contained in:
Jack Baldry
GitHub
@@ -0,0 +1,105 @@
|
||||
---
|
||||
aliases:
|
||||
- ../../http_api/ # /docs/grafana/next/http_api/
|
||||
- ../../overview/ # /docs/grafana/next/overview/
|
||||
- ../../../developers/http_api/ # /docs/grafana/developers/http_api/
|
||||
- ../../developers/http_api/ # /docs/grafana/next/developers/http_api/
|
||||
canonical: https://grafana.com/docs/grafana/latest/developer-resources/api-reference/http-api/
|
||||
description: Grafana HTTP API
|
||||
keywords:
|
||||
- grafana
|
||||
- http
|
||||
- documentation
|
||||
- api
|
||||
- overview
|
||||
labels:
|
||||
products:
|
||||
- enterprise
|
||||
- oss
|
||||
- cloud
|
||||
title: HTTP API
|
||||
weight: 100
|
||||
---
|
||||
|
||||
# Grafana HTTP API reference
|
||||
|
||||
Every Grafana instance exposes an HTTP API, which is the same API used by the Grafana frontend to manage resources like saving dashboards, creating users, updating data sources, deleting alerts, and more. You can use the HTTP API to programmatically access or manage resources from your Grafana instance running in Grafana Cloud. Below is the list of existing [HTTP APIs](#http-apis).
|
||||
|
||||
HTTP API details are [specified](https://editor.swagger.io/?url=https://raw.githubusercontent.com/grafana/grafana/main/public/api-merged.json) using OpenAPI v2.
|
||||
|
||||
There is also an [OpenAPI v3 specification](https://editor.swagger.io/?url=https://raw.githubusercontent.com/grafana/grafana/main/public/openapi3.json) (generated by the v2 one).
|
||||
|
||||
Users can browser and try out both via the Swagger UI editor (served by the Grafana server) by navigating to `/swagger-ui`.
|
||||
|
||||
{{< admonition type="note" >}}
|
||||
|
||||
If you need to manage or access other resources from your [Grafana Cloud Stack](/docs/grafana-cloud/account-management/cloud-stacks/), refer to the [Grafana Cloud API](../cloud-api/) instead.
|
||||
|
||||
{{< /admonition >}}
|
||||
|
||||
## Authenticate HTTP API requests
|
||||
|
||||
### Grafana OSS
|
||||
|
||||
{{< docs/shared lookup="developers/authentication.md" source="grafana" version="<GRAFANA_VERSION>" >}}
|
||||
|
||||
### Grafana Cloud
|
||||
|
||||
{{< docs/shared source="grafana-cloud" lookup="/developer-resources/authentication.md" version="" >}}
|
||||
|
||||
## X-Grafana-Org-Id Header
|
||||
|
||||
**X-Grafana-Org-Id** is an optional property that specifies the organization to which the action is applied. If it is not set, the created key belongs to the current context org. Use this header in all requests except those regarding admin.
|
||||
|
||||
**Example Request**:
|
||||
|
||||
```http
|
||||
GET /api/org/ HTTP/1.1
|
||||
Accept: application/json
|
||||
Content-Type: application/json
|
||||
X-Grafana-Org-Id: 2
|
||||
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
|
||||
```
|
||||
|
||||
## HTTP APIs
|
||||
|
||||
- [Admin API](admin/)
|
||||
- [Alerting API (unstable)](https://editor.swagger.io/?url=https://raw.githubusercontent.com/grafana/grafana/main/pkg/services/ngalert/api/tooling/post.json)
|
||||
- [Alerting provisioning API](alerting_provisioning/)
|
||||
- [Annotations API](annotations/)
|
||||
- [Correlations API](correlations/)
|
||||
- [Dashboard API](dashboard/)
|
||||
- [Dashboard permissions API](dashboard_permissions/)
|
||||
- [Dashboard versions API](dashboard_versions/)
|
||||
- [Data source API](data_source/)
|
||||
- [Folder API](folder/)
|
||||
- [Folder permissions API](folder_permissions/)
|
||||
- [Folder/Dashboard search API](folder_dashboard_search/)
|
||||
- [Library element API](library_element/)
|
||||
- [Organization API](org/)
|
||||
- [Other API](other/)
|
||||
- [Playlists API](playlist/)
|
||||
- [Preferences API](preferences/)
|
||||
- [Shared dashboards API](dashboard_public/)
|
||||
- [Query history API](query_history/)
|
||||
- [Service account API](serviceaccount/)
|
||||
- [Short URL API](short_url/)
|
||||
- [Snapshot API](snapshot/)
|
||||
- [SSO settings API](sso-settings/)
|
||||
- [Team API](team/)
|
||||
- [User API](user/)
|
||||
|
||||
## Grafana Enterprise HTTP APIs
|
||||
|
||||
Grafana Enterprise includes all of the Grafana OSS APIs as well as the following APIs:
|
||||
|
||||
- [Data source permissions API](datasource_permissions/)
|
||||
- [License API](licensing/)
|
||||
- [Query and resource caching API](query_and_resource_caching/)
|
||||
- [Reporting API](reporting/)
|
||||
- [Role-based access control API](access_control/)
|
||||
- [Team sync API](team_sync/)
|
||||
|
||||
## Deprecated HTTP APIs
|
||||
|
||||
- [Authentication API](authentication/)
|
||||
File diff suppressed because it is too large
Load Diff
776
docs/sources/developer-resources/api-reference/http-api/admin.md
Normal file
776
docs/sources/developer-resources/api-reference/http-api/admin.md
Normal file
@@ -0,0 +1,776 @@
|
||||
---
|
||||
aliases:
|
||||
- ../../../http_api/admin/ # /docs/grafana/next/http_api/admin/
|
||||
- ../../../developers/http_api/admin/ # /docs/grafana/next/developers/http_api/admin/
|
||||
canonical: https://grafana.com/docs/grafana/latest/developer-resources/api-reference/http-api/admin/
|
||||
description: Grafana Admin HTTP API
|
||||
keywords:
|
||||
- grafana
|
||||
- http
|
||||
- documentation
|
||||
- api
|
||||
- admin
|
||||
labels:
|
||||
products:
|
||||
- enterprise
|
||||
- oss
|
||||
title: 'Admin HTTP API '
|
||||
---
|
||||
|
||||
# Admin API
|
||||
|
||||
{{< admonition type="caution" >}}
|
||||
You can't authenticate to the Admin HTTP API with service account tokens.
|
||||
Service accounts are limited to an organization and an organization role.
|
||||
They can't be granted [Grafana server administrator permissions](/docs/grafana/<GRAFANA_VERSION>/administration/roles-and-permissions/#grafana-server-administrators).
|
||||
|
||||
To use these API endpoints you have to use Basic authentication and the Grafana user must have the Grafana server administrator permission.
|
||||
|
||||
The `admin` user that Grafana is provisioned with by default has permissions to use these API endpoints.
|
||||
{{< /admonition >}}
|
||||
|
||||
> If you are running Grafana Enterprise, for some endpoints you'll need to have specific permissions. Refer to [Role-based access control permissions](/docs/grafana/<GRAFANA_VERSION>/administration/roles-and-permissions/access-control/custom-role-actions-scopes/) for more information.
|
||||
|
||||
## Fetch settings
|
||||
|
||||
`GET /api/admin/settings`
|
||||
|
||||
Only works with Basic Authentication (username and password). See [introduction](/docs/grafana/<GRAFANA_VERSION>/http_api/admin/#admin-api) for an explanation.
|
||||
|
||||
**Required permissions**
|
||||
|
||||
See note in the [introduction](#admin-api) for an explanation.
|
||||
|
||||
| Action | Scope |
|
||||
| ------------- | ----------------------------------------------------------------------------------- |
|
||||
| settings:read | settings:\*_<br>settings:auth.saml:_<br>settings:auth.saml:enabled (property level) |
|
||||
|
||||
**Example Request**:
|
||||
|
||||
```http
|
||||
GET /api/admin/settings
|
||||
Accept: application/json
|
||||
Content-Type: application/json
|
||||
```
|
||||
|
||||
**Example Response**:
|
||||
|
||||
```http
|
||||
HTTP/1.1 200
|
||||
Content-Type: application/json
|
||||
|
||||
```
|
||||
|
||||
## Update settings
|
||||
|
||||
`PUT /api/admin/settings`
|
||||
|
||||
{{< admonition type="note" >}}
|
||||
Available in Grafana Enterprise v8.0+.
|
||||
{{< /admonition >}}
|
||||
|
||||
Updates / removes and reloads database settings. You must provide either `updates`, `removals` or both.
|
||||
|
||||
This endpoint only supports changes to `auth.saml` configuration.
|
||||
|
||||
**Required permissions**
|
||||
|
||||
See note in the [introduction](#admin-api) for an explanation.
|
||||
|
||||
| Action | Scope |
|
||||
| -------------- | ----------------------------------------------------------------------------------- |
|
||||
| settings:write | settings:\*_<br>settings:auth.saml:_<br>settings:auth.saml:enabled (property level) |
|
||||
|
||||
**Example request:**
|
||||
|
||||
```http
|
||||
PUT /api/admin/settings
|
||||
Accept: application/json
|
||||
Content-Type: application/json
|
||||
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
|
||||
|
||||
{
|
||||
"updates": {
|
||||
"auth.saml": {
|
||||
"enabled": "true"
|
||||
}
|
||||
},
|
||||
"removals": {
|
||||
"auth.saml": ["single_logout"]
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
**Example response:**
|
||||
|
||||
```http
|
||||
HTTP/1.1 200 OK
|
||||
Content-Type: application/json
|
||||
Content-Length: 32
|
||||
|
||||
```
|
||||
|
||||
Status codes:
|
||||
|
||||
- **200** - OK
|
||||
- **400** - Bad Request
|
||||
- **401** - Unauthorized
|
||||
- **403** - Forbidden
|
||||
- **500** - Internal Server Error
|
||||
|
||||
## Grafana Stats
|
||||
|
||||
`GET /api/admin/stats`
|
||||
|
||||
Only works with Basic Authentication (username and password). See [introduction](/docs/grafana/<GRAFANA_VERSION>/http_api/admin/#admin-api) for an explanation.
|
||||
|
||||
**Required permissions**
|
||||
|
||||
See note in the [introduction](#admin-api) for an explanation.
|
||||
|
||||
| Action | Scope |
|
||||
| ----------------- | ----- |
|
||||
| server.stats:read | n/a |
|
||||
|
||||
**Example Request**:
|
||||
|
||||
```http
|
||||
GET /api/admin/stats
|
||||
Accept: application/json
|
||||
Content-Type: application/json
|
||||
```
|
||||
|
||||
**Example Response**:
|
||||
|
||||
```http
|
||||
HTTP/1.1 200
|
||||
Content-Type: application/json
|
||||
|
||||
```
|
||||
|
||||
## Grafana Usage Report preview
|
||||
|
||||
`GET /api/admin/usage-report-preview`
|
||||
|
||||
Preview usage report to be sent to vendor.
|
||||
|
||||
Only works with Basic Authentication (username and password). See [introduction](/docs/grafana/<GRAFANA_VERSION>/http_api/admin/#admin-api) for an explanation.
|
||||
|
||||
**Example Request**:
|
||||
|
||||
```http
|
||||
GET /api/admin/usage-report-preview
|
||||
Accept: application/json
|
||||
Content-Type: application/json
|
||||
```
|
||||
|
||||
**Example Response**:
|
||||
|
||||
```http
|
||||
HTTP/1.1 200
|
||||
Content-Type: application/json
|
||||
|
||||
```
|
||||
|
||||
## Global Users
|
||||
|
||||
`POST /api/admin/users`
|
||||
|
||||
Create new user. Only works with Basic Authentication (username and password). See [introduction](/docs/grafana/<GRAFANA_VERSION>/http_api/admin/#admin-api) for an explanation.
|
||||
|
||||
**Required permissions**
|
||||
|
||||
See note in the [introduction](#admin-api) for an explanation.
|
||||
|
||||
| Action | Scope |
|
||||
| ------------ | ----- |
|
||||
| users:create | n/a |
|
||||
|
||||
**Example Request**:
|
||||
|
||||
```http
|
||||
POST /api/admin/users HTTP/1.1
|
||||
Accept: application/json
|
||||
Content-Type: application/json
|
||||
|
||||
```
|
||||
|
||||
Note that `OrgId` is an optional parameter that can be used to assign a new user to a different organization when [auto_assign_org](/docs/grafana/<GRAFANA_VERSION>/setup-grafana/configure-grafana/#auto-assign-org) is set to `true`.
|
||||
|
||||
**Example Response**:
|
||||
|
||||
```http
|
||||
HTTP/1.1 200
|
||||
Content-Type: application/json
|
||||
|
||||
```
|
||||
|
||||
## Password for User
|
||||
|
||||
`PUT /api/admin/users/:id/password`
|
||||
|
||||
Only works with Basic Authentication (username and password). See [introduction](/docs/grafana/<GRAFANA_VERSION>/http_api/admin/#admin-api) for an explanation.
|
||||
Change password for a specific user.
|
||||
|
||||
**Required permissions**
|
||||
|
||||
See note in the [introduction](#admin-api) for an explanation.
|
||||
|
||||
| Action | Scope |
|
||||
| -------------------- | --------------- |
|
||||
| users.password:write | global.users:\* |
|
||||
|
||||
**Example Request**:
|
||||
|
||||
```http
|
||||
PUT /api/admin/users/2/password HTTP/1.1
|
||||
Accept: application/json
|
||||
Content-Type: application/json
|
||||
|
||||
```
|
||||
|
||||
**Example Response**:
|
||||
|
||||
```http
|
||||
HTTP/1.1 200
|
||||
Content-Type: application/json
|
||||
|
||||
```
|
||||
|
||||
## Permissions
|
||||
|
||||
`PUT /api/admin/users/:id/permissions`
|
||||
|
||||
Only works with Basic Authentication (username and password). See [introduction](/docs/grafana/<GRAFANA_VERSION>/http_api/admin/#admin-api) for an explanation.
|
||||
|
||||
**Required permissions**
|
||||
|
||||
See note in the [introduction](#admin-api) for an explanation.
|
||||
|
||||
| Action | Scope |
|
||||
| ----------------------- | --------------- |
|
||||
| users.permissions:write | global.users:\* |
|
||||
|
||||
**Example Request**:
|
||||
|
||||
```http
|
||||
PUT /api/admin/users/2/permissions HTTP/1.1
|
||||
Accept: application/json
|
||||
Content-Type: application/json
|
||||
|
||||
```
|
||||
|
||||
**Example Response**:
|
||||
|
||||
```http
|
||||
HTTP/1.1 200
|
||||
Content-Type: application/json
|
||||
|
||||
```
|
||||
|
||||
## Delete global User
|
||||
|
||||
`DELETE /api/admin/users/:id`
|
||||
|
||||
Only works with Basic Authentication (username and password). See [introduction](/docs/grafana/<GRAFANA_VERSION>/http_api/admin/#admin-api) for an explanation.
|
||||
|
||||
**Required permissions**
|
||||
|
||||
See note in the [introduction](#admin-api) for an explanation.
|
||||
|
||||
| Action | Scope |
|
||||
| ------------ | --------------- |
|
||||
| users:delete | global.users:\* |
|
||||
|
||||
**Example Request**:
|
||||
|
||||
```http
|
||||
DELETE /api/admin/users/2 HTTP/1.1
|
||||
Accept: application/json
|
||||
Content-Type: application/json
|
||||
```
|
||||
|
||||
**Example Response**:
|
||||
|
||||
```http
|
||||
HTTP/1.1 200
|
||||
Content-Type: application/json
|
||||
|
||||
```
|
||||
|
||||
## Auth tokens for User
|
||||
|
||||
`GET /api/admin/users/:id/auth-tokens`
|
||||
|
||||
Return a list of all auth tokens (devices) that the user currently have logged in from.
|
||||
|
||||
Only works with Basic Authentication (username and password). See [introduction](/docs/grafana/<GRAFANA_VERSION>/http_api/admin/#admin-api) for an explanation.
|
||||
|
||||
**Required permissions**
|
||||
|
||||
See note in the [introduction](#admin-api) for an explanation.
|
||||
|
||||
| Action | Scope |
|
||||
| -------------------- | --------------- |
|
||||
| users.authtoken:read | global.users:\* |
|
||||
|
||||
**Example Request**:
|
||||
|
||||
```http
|
||||
GET /api/admin/users/1/auth-tokens HTTP/1.1
|
||||
Accept: application/json
|
||||
Content-Type: application/json
|
||||
```
|
||||
|
||||
**Example Response**:
|
||||
|
||||
```http
|
||||
HTTP/1.1 200
|
||||
Content-Type: application/json
|
||||
|
||||
```
|
||||
|
||||
## Revoke auth token for User
|
||||
|
||||
`POST /api/admin/users/:id/revoke-auth-token`
|
||||
|
||||
Revokes the given auth token (device) for the user. User of issued auth token (device) will no longer be logged in
|
||||
and will be required to authenticate again upon next activity.
|
||||
|
||||
Only works with Basic Authentication (username and password). See [introduction](/docs/grafana/<GRAFANA_VERSION>/http_api/admin/#admin-api) for an explanation.
|
||||
|
||||
**Required permissions**
|
||||
|
||||
See note in the [introduction](#admin-api) for an explanation.
|
||||
|
||||
| Action | Scope |
|
||||
| --------------------- | --------------- |
|
||||
| users.authtoken:write | global.users:\* |
|
||||
|
||||
**Example Request**:
|
||||
|
||||
```http
|
||||
POST /api/admin/users/1/revoke-auth-token HTTP/1.1
|
||||
Accept: application/json
|
||||
Content-Type: application/json
|
||||
|
||||
```
|
||||
|
||||
**Example Response**:
|
||||
|
||||
```http
|
||||
HTTP/1.1 200
|
||||
Content-Type: application/json
|
||||
|
||||
```
|
||||
|
||||
## Logout User
|
||||
|
||||
`POST /api/admin/users/:id/logout`
|
||||
|
||||
Logout user revokes all auth tokens (devices) for the user. User of issued auth tokens (devices) will no longer be logged in
|
||||
and will be required to authenticate again upon next activity.
|
||||
|
||||
Only works with Basic Authentication (username and password). See [introduction](/docs/grafana/<GRAFANA_VERSION>/http_api/admin/#admin-api) for an explanation.
|
||||
|
||||
**Required permissions**
|
||||
|
||||
See note in the [introduction](#admin-api) for an explanation.
|
||||
|
||||
| Action | Scope |
|
||||
| ------------ | --------------- |
|
||||
| users.logout | global.users:\* |
|
||||
|
||||
**Example Request**:
|
||||
|
||||
```http
|
||||
POST /api/admin/users/1/logout HTTP/1.1
|
||||
Accept: application/json
|
||||
Content-Type: application/json
|
||||
```
|
||||
|
||||
**Example Response**:
|
||||
|
||||
```http
|
||||
HTTP/1.1 200
|
||||
Content-Type: application/json
|
||||
|
||||
```
|
||||
|
||||
## Reload provisioning configurations
|
||||
|
||||
`POST /api/admin/provisioning/dashboards/reload`
|
||||
|
||||
`POST /api/admin/provisioning/datasources/reload`
|
||||
|
||||
`POST /api/admin/provisioning/plugins/reload`
|
||||
|
||||
`POST /api/admin/provisioning/access-control/reload`
|
||||
|
||||
`POST /api/admin/provisioning/alerting/reload`
|
||||
|
||||
Reloads the provisioning config files for specified type and provision entities again. It won't return
|
||||
until the new provisioned entities are already stored in the database. In case of dashboards, it will stop
|
||||
polling for changes in dashboard files and then restart it with new configurations after returning.
|
||||
|
||||
Only works with Basic Authentication (username and password). See [introduction](/docs/grafana/<GRAFANA_VERSION>/http_api/admin/#admin-api) for an explanation.
|
||||
|
||||
**Required permissions**
|
||||
|
||||
See note in the [introduction](#admin-api) for an explanation.
|
||||
|
||||
| Action | Scope | Provision entity |
|
||||
| ------------------- | -------------------------- | ---------------- |
|
||||
| provisioning:reload | provisioners:accesscontrol | accesscontrol |
|
||||
| provisioning:reload | provisioners:dashboards | dashboards |
|
||||
| provisioning:reload | provisioners:datasources | datasources |
|
||||
| provisioning:reload | provisioners:plugins | plugins |
|
||||
| provisioning:reload | provisioners:alerting | alerting |
|
||||
|
||||
**Example Request**:
|
||||
|
||||
```http
|
||||
POST /api/admin/provisioning/dashboards/reload HTTP/1.1
|
||||
Accept: application/json
|
||||
Content-Type: application/json
|
||||
```
|
||||
|
||||
**Example Response**:
|
||||
|
||||
```http
|
||||
HTTP/1.1 200
|
||||
Content-Type: application/json
|
||||
|
||||
```
|
||||
|
||||
## Reload LDAP configuration
|
||||
|
||||
`POST /api/admin/ldap/reload`
|
||||
|
||||
Reloads the LDAP configuration.
|
||||
|
||||
Only works with Basic Authentication (username and password). See [introduction](/docs/grafana/<GRAFANA_VERSION>/http_api/admin/#admin-api) for an explanation.
|
||||
|
||||
**Example Request**:
|
||||
|
||||
```http
|
||||
POST /api/admin/ldap/reload HTTP/1.1
|
||||
Accept: application/json
|
||||
Content-Type: application/json
|
||||
```
|
||||
|
||||
**Example Response**:
|
||||
|
||||
```http
|
||||
HTTP/1.1 200
|
||||
Content-Type: application/json
|
||||
|
||||
```
|
||||
|
||||
## Rotate data encryption keys
|
||||
|
||||
`POST /api/admin/encryption/rotate-data-keys`
|
||||
|
||||
[Rotates](/docs/grafana/<GRAFANA_VERSION>/setup-grafana/configure-security/configure-database-encryption/#rotate-data-keys) data encryption keys.
|
||||
|
||||
**Example Request**:
|
||||
|
||||
```http
|
||||
POST /api/admin/encryption/rotate-data-keys HTTP/1.1
|
||||
Accept: application/json
|
||||
Content-Type: application/json
|
||||
```
|
||||
|
||||
**Example Response**:
|
||||
|
||||
```http
|
||||
HTTP/1.1 204
|
||||
Content-Type: application/json
|
||||
```
|
||||
|
||||
## Re-encrypt data encryption keys
|
||||
|
||||
`POST /api/admin/encryption/reencrypt-data-keys`
|
||||
|
||||
[Re-encrypts](/docs/grafana/<GRAFANA_VERSION>/setup-grafana/configure-security/configure-database-encryption/#re-encrypt-data-keys) data encryption keys.
|
||||
|
||||
**Example Request**:
|
||||
|
||||
```http
|
||||
POST /api/admin/encryption/reencrypt-data-keys HTTP/1.1
|
||||
Accept: application/json
|
||||
Content-Type: application/json
|
||||
```
|
||||
|
||||
**Example Response**:
|
||||
|
||||
```http
|
||||
HTTP/1.1 204
|
||||
Content-Type: application/json
|
||||
```
|
||||
|
||||
## Re-encrypt secrets
|
||||
|
||||
`POST /api/admin/encryption/reencrypt-secrets`
|
||||
|
||||
[Re-encrypts](/docs/grafana/<GRAFANA_VERSION>/setup-grafana/configure-security/configure-database-encryption/#re-encrypt-secrets) secrets.
|
||||
|
||||
**Example Request**:
|
||||
|
||||
```http
|
||||
POST /api/admin/encryption/reencrypt-secrets HTTP/1.1
|
||||
Accept: application/json
|
||||
Content-Type: application/json
|
||||
```
|
||||
|
||||
**Example Response**:
|
||||
|
||||
```http
|
||||
HTTP/1.1 204
|
||||
Content-Type: application/json
|
||||
```
|
||||
|
||||
## Roll back secrets
|
||||
|
||||
`POST /api/admin/encryption/rollback-secrets`
|
||||
|
||||
[Rolls back](/docs/grafana/<GRAFANA_VERSION>/setup-grafana/configure-security/configure-database-encryption/#roll-back-secrets) secrets.
|
||||
|
||||
**Example Request**:
|
||||
|
||||
```http
|
||||
POST /api/admin/encryption/rollback-secrets HTTP/1.1
|
||||
Accept: application/json
|
||||
Content-Type: application/json
|
||||
```
|
||||
|
||||
**Example Response**:
|
||||
|
||||
```http
|
||||
HTTP/1.1 204
|
||||
Content-Type: application/json
|
||||
```
|
||||
See note in the [introduction](#admin-api) for an explanation.
|
||||
|
||||
| Action | Scope |
|
||||
| --------------------- | --------------- |
|
||||
| users.authtoken:write | global.users:\* |
|
||||
|
||||
**Example Request**:
|
||||
|
||||
```http
|
||||
POST /api/admin/users/1/revoke-auth-token HTTP/1.1
|
||||
Accept: application/json
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"authTokenId": 364
|
||||
}
|
||||
```
|
||||
|
||||
**Example Response**:
|
||||
|
||||
```http
|
||||
HTTP/1.1 200
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"message": "User auth token revoked"
|
||||
}
|
||||
```
|
||||
|
||||
## Logout User
|
||||
|
||||
`POST /api/admin/users/:id/logout`
|
||||
|
||||
Logout user revokes all auth tokens (devices) for the user. User of issued auth tokens (devices) will no longer be logged in
|
||||
and will be required to authenticate again upon next activity.
|
||||
|
||||
Only works with Basic Authentication (username and password). See [introduction](/docs/grafana/<GRAFANA_VERSION>/http_api/admin/#admin-api) for an explanation.
|
||||
|
||||
**Required permissions**
|
||||
|
||||
See note in the [introduction](#admin-api) for an explanation.
|
||||
|
||||
| Action | Scope |
|
||||
| ------------ | --------------- |
|
||||
| users.logout | global.users:\* |
|
||||
|
||||
**Example Request**:
|
||||
|
||||
```http
|
||||
POST /api/admin/users/1/logout HTTP/1.1
|
||||
Accept: application/json
|
||||
Content-Type: application/json
|
||||
```
|
||||
|
||||
**Example Response**:
|
||||
|
||||
```http
|
||||
HTTP/1.1 200
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"message": "User auth token revoked"
|
||||
}
|
||||
```
|
||||
|
||||
## Reload provisioning configurations
|
||||
|
||||
`POST /api/admin/provisioning/dashboards/reload`
|
||||
|
||||
`POST /api/admin/provisioning/datasources/reload`
|
||||
|
||||
`POST /api/admin/provisioning/plugins/reload`
|
||||
|
||||
`POST /api/admin/provisioning/access-control/reload`
|
||||
|
||||
`POST /api/admin/provisioning/alerting/reload`
|
||||
|
||||
Reloads the provisioning config files for specified type and provision entities again. It won't return
|
||||
until the new provisioned entities are already stored in the database. In case of dashboards, it will stop
|
||||
polling for changes in dashboard files and then restart it with new configurations after returning.
|
||||
|
||||
Only works with Basic Authentication (username and password). See [introduction](/docs/grafana/<GRAFANA_VERSION>/http_api/admin/#admin-api) for an explanation.
|
||||
|
||||
**Required permissions**
|
||||
|
||||
See note in the [introduction](#admin-api) for an explanation.
|
||||
|
||||
| Action | Scope | Provision entity |
|
||||
| ------------------- | -------------------------- | ---------------- |
|
||||
| provisioning:reload | provisioners:accesscontrol | accesscontrol |
|
||||
| provisioning:reload | provisioners:dashboards | dashboards |
|
||||
| provisioning:reload | provisioners:datasources | datasources |
|
||||
| provisioning:reload | provisioners:plugins | plugins |
|
||||
| provisioning:reload | provisioners:alerting | alerting |
|
||||
|
||||
**Example Request**:
|
||||
|
||||
```http
|
||||
POST /api/admin/provisioning/dashboards/reload HTTP/1.1
|
||||
Accept: application/json
|
||||
Content-Type: application/json
|
||||
```
|
||||
|
||||
**Example Response**:
|
||||
|
||||
```http
|
||||
HTTP/1.1 200
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"message": "Dashboards config reloaded"
|
||||
}
|
||||
```
|
||||
|
||||
## Reload LDAP configuration
|
||||
|
||||
`POST /api/admin/ldap/reload`
|
||||
|
||||
Reloads the LDAP configuration.
|
||||
|
||||
Only works with Basic Authentication (username and password). See [introduction](/docs/grafana/<GRAFANA_VERSION>/http_api/admin/#admin-api) for an explanation.
|
||||
|
||||
**Example Request**:
|
||||
|
||||
```http
|
||||
POST /api/admin/ldap/reload HTTP/1.1
|
||||
Accept: application/json
|
||||
Content-Type: application/json
|
||||
```
|
||||
|
||||
**Example Response**:
|
||||
|
||||
```http
|
||||
HTTP/1.1 200
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"message": "LDAP config reloaded"
|
||||
}
|
||||
```
|
||||
|
||||
## Rotate data encryption keys
|
||||
|
||||
`POST /api/admin/encryption/rotate-data-keys`
|
||||
|
||||
[Rotates](/docs/grafana/<GRAFANA_VERSION>/setup-grafana/configure-security/configure-database-encryption/#rotate-data-keys) data encryption keys.
|
||||
|
||||
**Example Request**:
|
||||
|
||||
```http
|
||||
POST /api/admin/encryption/rotate-data-keys HTTP/1.1
|
||||
Accept: application/json
|
||||
Content-Type: application/json
|
||||
```
|
||||
|
||||
**Example Response**:
|
||||
|
||||
```http
|
||||
HTTP/1.1 204
|
||||
Content-Type: application/json
|
||||
```
|
||||
|
||||
## Re-encrypt data encryption keys
|
||||
|
||||
`POST /api/admin/encryption/reencrypt-data-keys`
|
||||
|
||||
[Re-encrypts](/docs/grafana/<GRAFANA_VERSION>/setup-grafana/configure-security/configure-database-encryption/#re-encrypt-data-keys) data encryption keys.
|
||||
|
||||
**Example Request**:
|
||||
|
||||
```http
|
||||
POST /api/admin/encryption/reencrypt-data-keys HTTP/1.1
|
||||
Accept: application/json
|
||||
Content-Type: application/json
|
||||
```
|
||||
|
||||
**Example Response**:
|
||||
|
||||
```http
|
||||
HTTP/1.1 204
|
||||
Content-Type: application/json
|
||||
```
|
||||
|
||||
## Re-encrypt secrets
|
||||
|
||||
`POST /api/admin/encryption/reencrypt-secrets`
|
||||
|
||||
[Re-encrypts](/docs/grafana/<GRAFANA_VERSION>/setup-grafana/configure-security/configure-database-encryption/#re-encrypt-secrets) secrets.
|
||||
|
||||
**Example Request**:
|
||||
|
||||
```http
|
||||
POST /api/admin/encryption/reencrypt-secrets HTTP/1.1
|
||||
Accept: application/json
|
||||
Content-Type: application/json
|
||||
```
|
||||
|
||||
**Example Response**:
|
||||
|
||||
```http
|
||||
HTTP/1.1 204
|
||||
Content-Type: application/json
|
||||
```
|
||||
|
||||
## Roll back secrets
|
||||
|
||||
`POST /api/admin/encryption/rollback-secrets`
|
||||
|
||||
[Rolls back](/docs/grafana/<GRAFANA_VERSION>/setup-grafana/configure-security/configure-database-encryption/#roll-back-secrets) secrets.
|
||||
|
||||
**Example Request**:
|
||||
|
||||
```http
|
||||
POST /api/admin/encryption/rollback-secrets HTTP/1.1
|
||||
Accept: application/json
|
||||
Content-Type: application/json
|
||||
```
|
||||
|
||||
**Example Response**:
|
||||
|
||||
```http
|
||||
HTTP/1.1 204
|
||||
Content-Type: application/json
|
||||
```
|
||||
@@ -0,0 +1,24 @@
|
||||
---
|
||||
aliases:
|
||||
- ../../../http_api/alerting_provisioning/ # /docs/grafana/next/http_api/alerting_provisioning/
|
||||
- ../../../developers/http_api/alerting_provisioning/ # /docs/grafana/next/developers/http_api/alerting_provisioning/
|
||||
canonical: https://grafana.com/docs/grafana/latest/developer-resources/api-reference/http-api/alerting_provisioning/
|
||||
description: Grafana Alerts HTTP API
|
||||
keywords:
|
||||
- grafana
|
||||
- http
|
||||
- documentation
|
||||
- api
|
||||
- alerting
|
||||
- alerts
|
||||
labels:
|
||||
products:
|
||||
- cloud
|
||||
- enterprise
|
||||
- oss
|
||||
title: 'Alerting Provisioning HTTP API '
|
||||
---
|
||||
|
||||
# Alerting provisioning HTTP API
|
||||
|
||||
{{< docs/shared lookup="alerts/alerting_provisioning.md" source="grafana" version="<GRAFANA_VERSION>" >}}
|
||||
@@ -0,0 +1,380 @@
|
||||
---
|
||||
aliases:
|
||||
- ../../../http_api/annotations/ # /docs/grafana/next/http_api/annotations/
|
||||
- ../../../developers/http_api/annotations/ # /docs/grafana/next/developers/http_api/annotations/
|
||||
canonical: https://grafana.com/docs/grafana/latest/developer-resources/api-reference/http-api/annotations/
|
||||
description: Grafana Annotations HTTP API
|
||||
keywords:
|
||||
- grafana
|
||||
- http
|
||||
- documentation
|
||||
- api
|
||||
- annotation
|
||||
- annotations
|
||||
- comment
|
||||
labels:
|
||||
products:
|
||||
- enterprise
|
||||
- oss
|
||||
- cloud
|
||||
title: Annotations HTTP API
|
||||
---
|
||||
|
||||
# Annotations API
|
||||
|
||||
Annotations are saved in the Grafana database (sqlite, mysql or postgres). Annotations can be organization annotations that can be shown on any dashboard by configuring an annotation data source - they are filtered by tags. Or they can be tied to a panel on a dashboard and are then only shown on that panel.
|
||||
|
||||
> If you are running Grafana Enterprise, for some endpoints you'll need to have specific permissions. Refer to [Role-based access control permissions](/docs/grafana/latest/administration/roles-and-permissions/access-control/custom-role-actions-scopes/) for more information.
|
||||
|
||||
## Find Annotations
|
||||
|
||||
`GET /api/annotations?from=1506676478816&to=1507281278816&tags=tag1&tags=tag2&limit=100`
|
||||
|
||||
**Required permissions**
|
||||
|
||||
See note in the [introduction](#annotations-api) for an explanation.
|
||||
|
||||
<!-- prettier-ignore-start -->
|
||||
| Action | Scope |
|
||||
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
||||
| `annotations:read` | <ul><li>`annotations:*`</li><li>`annotations:type:*`</li><li>`dashboards:*`</li><li>`dashboards:uid:*`</li><li>`folders:*`</li><li>`folders:uid:*`</li></ul> |
|
||||
{ .no-spacing-list }
|
||||
<!-- prettier-ignore-end -->
|
||||
|
||||
**Example Request**:
|
||||
|
||||
```http
|
||||
GET /api/annotations?from=1506676478816&to=1507281278816&tags=tag1&tags=tag2&limit=100 HTTP/1.1
|
||||
Accept: application/json
|
||||
Content-Type: application/json
|
||||
Authorization: Basic YWRtaW46YWRtaW4=
|
||||
```
|
||||
|
||||
Query Parameters:
|
||||
|
||||
- `from`: epoch datetime in milliseconds. Optional.
|
||||
- `to`: epoch datetime in milliseconds. Optional.
|
||||
- `limit`: number. Optional - default is 100. Max limit for results returned.
|
||||
- `alertId`: number. Optional. Find annotations for a specified alert.
|
||||
- `dashboardId`: Deprecated. Use dashboardUID instead.
|
||||
- `dashboardUID`: string. Optional. Find annotations that are scoped to a specific dashboard, when dashboardUID presents, dashboardId would be ignored.
|
||||
- `panelId`: number. Optional. Find annotations that are scoped to a specific panel
|
||||
- `userId`: number. Optional. Find annotations created by a specific user
|
||||
- `type`: string. Optional. `alert`|`annotation` Return alerts or user created annotations
|
||||
- `tags`: string. Optional. Use this to filter organization annotations. Organization 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 e.g. `tags=tag1&tags=tag2`.
|
||||
|
||||
**Example Response**:
|
||||
|
||||
```http
|
||||
HTTP/1.1 200
|
||||
Content-Type: application/json
|
||||
[
|
||||
```
|
||||
|
||||
> Starting in Grafana v6.4 regions annotations are now returned in one entity that now includes the timeEnd property.
|
||||
|
||||
## Create Annotation
|
||||
|
||||
Creates an annotation in the Grafana database. The `dashboardUid` and `panelId` fields are optional.
|
||||
If they are not specified then an organization annotation is created and can be queried in any dashboard that adds
|
||||
the Grafana annotations data source. When creating a region annotation include the timeEnd property.
|
||||
|
||||
The format for `time` and `timeEnd` should be epoch numbers in millisecond resolution.
|
||||
|
||||
`POST /api/annotations`
|
||||
|
||||
**Required permissions**
|
||||
|
||||
See note in the [introduction](#annotations-api) for an explanation.
|
||||
|
||||
<!-- prettier-ignore-start -->
|
||||
| Action | Scope |
|
||||
| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
||||
| `annotations:create` | <ul><li>`annotations:*`</li><li>`annotations:type:*`</li><li>`dashboards:*`</li><li>`dashboards:uid:*`</li><li>`folders:*`</li><li>`folders:uid:*`</li></ul> |
|
||||
{ .no-spacing-list }
|
||||
<!-- prettier-ignore-end -->
|
||||
|
||||
**Required JSON Body Fields**
|
||||
|
||||
- `text`: description of the annotation.
|
||||
|
||||
**Example Request**:
|
||||
|
||||
```http
|
||||
POST /api/annotations HTTP/1.1
|
||||
Accept: application/json
|
||||
Content-Type: application/json
|
||||
|
||||
```
|
||||
|
||||
**Example Response**:
|
||||
|
||||
```http
|
||||
HTTP/1.1 200
|
||||
Content-Type: application/json
|
||||
|
||||
```
|
||||
|
||||
> The response for this HTTP request is slightly different in versions prior to v6.4. In prior versions you would
|
||||
> also get an endId if you where creating a region. But in 6.4 regions are represented using a single event with time and
|
||||
> timeEnd properties.
|
||||
|
||||
## Create Annotation in Graphite format
|
||||
|
||||
Creates an annotation by using Graphite-compatible event format. The `when` and `data` fields are optional. If `when` is not specified then the current time will be 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).
|
||||
|
||||
`POST /api/annotations/graphite`
|
||||
|
||||
**Required permissions**
|
||||
|
||||
See note in the [introduction](#annotations-api) for an explanation.
|
||||
|
||||
| Action | Scope |
|
||||
| -------------------- | ------------------------------- |
|
||||
| `annotations:create` | `annotations:type:organization` |
|
||||
|
||||
**Example Request**:
|
||||
|
||||
```http
|
||||
POST /api/annotations/graphite HTTP/1.1
|
||||
Accept: application/json
|
||||
Content-Type: application/json
|
||||
|
||||
```
|
||||
|
||||
**Example Response**:
|
||||
|
||||
```http
|
||||
HTTP/1.1 200
|
||||
Content-Type: application/json
|
||||
|
||||
```
|
||||
|
||||
## Update Annotation
|
||||
|
||||
`PUT /api/annotations/:id`
|
||||
|
||||
Updates all properties of an annotation that matches the specified id. To only update certain property, consider using the [Patch Annotation](#patch-annotation) operation.
|
||||
|
||||
**Required permissions**
|
||||
|
||||
See note in the [introduction](#annotations-api) for an explanation.
|
||||
|
||||
<!-- prettier-ignore-start -->
|
||||
| Action | Scope |
|
||||
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
||||
| `annotations:write` | <ul><li>`annotations:*`</li><li>`annotations:type:*`</li><li>`dashboards:*`</li><li>`dashboards:uid:*`</li><li>`folders:*`</li><li>`folders:uid:*`</li></ul> |
|
||||
{ .no-spacing-list }
|
||||
<!-- prettier-ignore-end -->
|
||||
|
||||
**Example Request**:
|
||||
|
||||
```http
|
||||
PUT /api/annotations/1141 HTTP/1.1
|
||||
Accept: application/json
|
||||
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
|
||||
Content-Type: application/json
|
||||
|
||||
```
|
||||
|
||||
**Example Response**:
|
||||
|
||||
```http
|
||||
HTTP/1.1 200
|
||||
Content-Type: application/json
|
||||
|
||||
```
|
||||
|
||||
## Patch Annotation
|
||||
|
||||
`PATCH /api/annotations/:id`
|
||||
|
||||
Updates one or more properties of an annotation that matches the specified id.
|
||||
|
||||
This operation currently supports updating of the `text`, `tags`, `time` and `timeEnd` properties.
|
||||
|
||||
**Required permissions**
|
||||
|
||||
See note in the [introduction](#annotations-api) for an explanation.
|
||||
|
||||
<!-- prettier-ignore-start -->
|
||||
| Action | Scope |
|
||||
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
||||
| `annotations:write` | <ul><li>`annotations:*`</li><li>`annotations:type:*`</li><li>`dashboards:*`</li><li>`dashboards:uid:*`</li><li>`folders:*`</li><li>`folders:uid:*`</li></ul> |
|
||||
{ .no-spacing-list }
|
||||
<!-- prettier-ignore-end -->
|
||||
|
||||
**Example Request**:
|
||||
|
||||
```http
|
||||
PATCH /api/annotations/1145 HTTP/1.1
|
||||
Accept: application/json
|
||||
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
|
||||
Content-Type: application/json
|
||||
|
||||
```
|
||||
|
||||
**Example Response**:
|
||||
|
||||
```http
|
||||
HTTP/1.1 200
|
||||
Content-Type: application/json
|
||||
|
||||
```
|
||||
|
||||
## Delete Annotation By Id
|
||||
|
||||
`DELETE /api/annotations/:id`
|
||||
|
||||
Deletes the annotation that matches the specified id.
|
||||
|
||||
**Required permissions**
|
||||
|
||||
See note in the [introduction](#annotations-api) for an explanation.
|
||||
|
||||
<!-- prettier-ignore-start -->
|
||||
| Action | Scope |
|
||||
| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
||||
| `annotations:delete` | <ul><li>`annotations:*`</li><li>`annotations:type:*`</li><li>`dashboards:*`</li><li>`dashboards:uid:*`</li><li>`folders:*`</li><li>`folders:uid:*`</li></ul> |
|
||||
{ .no-spacing-list }
|
||||
<!-- prettier-ignore-end -->
|
||||
|
||||
**Example Request**:
|
||||
|
||||
```http
|
||||
DELETE /api/annotations/1 HTTP/1.1
|
||||
Accept: application/json
|
||||
Content-Type: application/json
|
||||
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
|
||||
```
|
||||
|
||||
**Example Response**:
|
||||
|
||||
```http
|
||||
HTTP/1.1 200
|
||||
Content-Type: application/json
|
||||
|
||||
```
|
||||
|
||||
## Find Annotations Tags
|
||||
|
||||
`GET /api/annotations/tags`
|
||||
|
||||
Find all the event tags created in the annotations.
|
||||
|
||||
**Required permissions**
|
||||
|
||||
See note in the [introduction](#annotations-api) for an explanation.
|
||||
|
||||
| Action | Scope |
|
||||
| ------------------ | ----- |
|
||||
| `annotations:read` | N/A |
|
||||
|
||||
**Example Request**:
|
||||
|
||||
```http
|
||||
GET /api/annotations/tags?tag=out HTTP/1.1
|
||||
Accept: application/json
|
||||
Content-Type: application/json
|
||||
Authorization: Basic YWRtaW46YWRtaW4=
|
||||
```
|
||||
|
||||
Query Parameters:
|
||||
|
||||
- `tag`: Optional. A string that you can use to filter tags.
|
||||
- `limit`: Optional. A number, where the default is 100. Max limit for results returned.
|
||||
|
||||
**Example Response**:
|
||||
|
||||
```http
|
||||
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.
|
||||
|
||||
**Required permissions**
|
||||
|
||||
See note in the [introduction](#annotations-api) for an explanation.
|
||||
|
||||
<!-- prettier-ignore-start -->
|
||||
| Action | Scope |
|
||||
| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
||||
| `annotations:delete` | <ul><li>`annotations:*`</li><li>`annotations:type:*`</li><li>`dashboards:*`</li><li>`dashboards:uid:*`</li><li>`folders:*`</li><li>`folders:uid:*`</li></ul> |
|
||||
{ .no-spacing-list }
|
||||
<!-- prettier-ignore-end -->
|
||||
|
||||
**Example Request**:
|
||||
|
||||
```http
|
||||
DELETE /api/annotations/1 HTTP/1.1
|
||||
Accept: application/json
|
||||
Content-Type: application/json
|
||||
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
|
||||
```
|
||||
|
||||
**Example Response**:
|
||||
|
||||
```http
|
||||
HTTP/1.1 200
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"message":"Annotation deleted"
|
||||
}
|
||||
```
|
||||
|
||||
## Find Annotations Tags
|
||||
|
||||
`GET /api/annotations/tags`
|
||||
|
||||
Find all the event tags created in the annotations.
|
||||
|
||||
**Required permissions**
|
||||
|
||||
See note in the [introduction](#annotations-api) for an explanation.
|
||||
|
||||
| Action | Scope |
|
||||
| ------------------ | ----- |
|
||||
| `annotations:read` | N/A |
|
||||
|
||||
**Example Request**:
|
||||
|
||||
```http
|
||||
GET /api/annotations/tags?tag=out HTTP/1.1
|
||||
Accept: application/json
|
||||
Content-Type: application/json
|
||||
Authorization: Basic YWRtaW46YWRtaW4=
|
||||
```
|
||||
|
||||
Query Parameters:
|
||||
|
||||
- `tag`: Optional. A string that you can use to filter tags.
|
||||
- `limit`: Optional. A number, where the default is 100. Max limit for results returned.
|
||||
|
||||
**Example Response**:
|
||||
|
||||
```http
|
||||
HTTP/1.1 200
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"result": {
|
||||
"tags": [
|
||||
{
|
||||
"tag": "outage",
|
||||
"count": 1
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
116
docs/sources/developer-resources/api-reference/http-api/apis.md
Normal file
116
docs/sources/developer-resources/api-reference/http-api/apis.md
Normal file
@@ -0,0 +1,116 @@
|
||||
---
|
||||
aliases:
|
||||
- ../../../http_api/new_api_structure/ # /docs/grafana/next/http_api/new_api_structure/
|
||||
- ../../../developers/http_api/apis/ # /docs/grafana/next/developers/http_api/apis/
|
||||
canonical: https://grafana.com/docs/grafana/latest/developer-resources/api-reference/http-api/apis/
|
||||
description: ''
|
||||
keywords:
|
||||
- grafana
|
||||
- http
|
||||
- documentation
|
||||
- api
|
||||
labels:
|
||||
products:
|
||||
- enterprise
|
||||
- oss
|
||||
- cloud
|
||||
title: New API Structure
|
||||
---
|
||||
|
||||
# Grafana's New API Structure
|
||||
|
||||
## Overview
|
||||
|
||||
Going forward, Grafana's HTTP API will follow a standardized API structure alongside consistent API versioning.
|
||||
|
||||
## API Path Structure
|
||||
|
||||
All Grafana APIs follow this standardized format:
|
||||
|
||||
```
|
||||
/apis/<group>/<version>/namespaces/<namespace>/<resource>[/<name>]
|
||||
```
|
||||
|
||||
Where the final `/<name>` segment is used for operations on individual resources (like Get, Update, Delete) and omitted for collection operations (like List, Create).
|
||||
|
||||
## Understanding the Components
|
||||
|
||||
### Group (`<group>`)
|
||||
|
||||
Groups organize related functionality into logical collections. For example `dashboard.grafana.app` will be used for all dashboard-related operations.
|
||||
|
||||
### Version (`<version>`)
|
||||
|
||||
These APIs will also uses semantic versioning with three stability levels:
|
||||
|
||||
| Level | Format | Description | Use Case | Enabled By Default? |
|
||||
| ----- | ---------- | --------------------------------------------------------------------------- | ------------------------ | ------------------- |
|
||||
| Alpha | `v1alpha1` | Early development stage. Unstable, may contain bugs, and subject to removal | For testing new features | No |
|
||||
| Beta | `v1beta1` | More stable than alpha, but may still have some changes | For non-critical use | No |
|
||||
| GA | `v1` | Generally Available. Stable with backward compatibility guarantees | For production use | Yes |
|
||||
|
||||
#### Alpha
|
||||
|
||||
Alpha versions should not be served unless explicitly enabled by a feature flag, and should be considered completely experimental and subject to major changes.
|
||||
An alpha version may undergo breaking changes without adding an additional version, and should not be relied upon by production workflows. Alpha versions may be removed completely, even without being promoted to a more stable level (e.g. an experimental API may be introduced as alpha for a new feature and subsequently removed completely, in case that feature gets canceled).
|
||||
|
||||
#### Beta
|
||||
|
||||
Beta versions should not contain breaking changes in the schema, but still may be subject to changes in handling logic or semantics.
|
||||
Breaking schema changes require a new published beta version (such as publishing `v1beta2` for breaking changes to the `v1beta1` schema).
|
||||
While beta versions are no longer considered experimental like alpha versions, they should still be disabled by default.
|
||||
|
||||
#### GA
|
||||
|
||||
GA versions are enabled by default, and can be treated as completely stable. The only changes that can be made to these APIs are bug fixes,
|
||||
and any other changes should instead result in a new published version of the API.
|
||||
|
||||
### Namespace (`<namespace>`)
|
||||
|
||||
Namespaces isolate resources within your Grafana instance. The format varies by deployment type:
|
||||
|
||||
#### OSS & On-Premise Grafana
|
||||
|
||||
- Default organization (org 1): `default`
|
||||
- Additional organizations: `org-<org_id>`
|
||||
|
||||
#### Grafana Cloud
|
||||
|
||||
- Format: `stacks-<stack_id>`
|
||||
- Your instance ID is the `stack_id`. You can find this value by either:
|
||||
- Going to grafana.com, clicking on your stack, and selecting "Details" on your Grafana instance
|
||||
- Accessing the /swagger page in your cloud instance, where the namespace will be automatically populated on the relevant endpoints
|
||||
|
||||
### Resource (`<resource>`)
|
||||
|
||||
Represents the core resource you want to interact with, such as:
|
||||
|
||||
- `dashboards`
|
||||
- `playlists`
|
||||
- `folders`
|
||||
|
||||
### Name (<name>)
|
||||
|
||||
The `<name>` is the unique identifier for a specific instance of a resource within its namespace and resource type. `<name>` is distinct from the metadata.uid field. The URL path will always use the metadata.name.
|
||||
|
||||
For example, to get a dashboard defined as:
|
||||
|
||||
```
|
||||
{
|
||||
"kind": "Dashboard",
|
||||
"apiVersion": "dashboard.grafana.app/v1beta1",
|
||||
"metadata": {
|
||||
"name": "production-overview", // This value IS used in the URL path
|
||||
"namespace": "default",
|
||||
"uid": "a1b2c3d4-e5f6-7890-g1h2-i3j4k5l6m7n8" // This value is NOT used in the URL path
|
||||
// ... other metadata
|
||||
},
|
||||
"spec": {
|
||||
// ... dashboard spec
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
You would use the following API call:
|
||||
|
||||
`GET /apis/dashboard.grafana.app/v1beta1/namespaces/default/dashboards/production-overview`
|
||||
@@ -0,0 +1,31 @@
|
||||
---
|
||||
canonical: https://grafana.com/docs/grafana/latest/developer-resources/api-reference/http-api/authentication/
|
||||
description: 'You can authenticate HTTP API requests using basic authentication or a service account token.'
|
||||
keywords:
|
||||
- grafana
|
||||
- http
|
||||
- documentation
|
||||
- api
|
||||
- role-based-access-control
|
||||
- acl
|
||||
- enterprise
|
||||
labels:
|
||||
products:
|
||||
- enterprise
|
||||
- oss
|
||||
title: Authentication options for the HTTP API
|
||||
menuTitle: Authentication
|
||||
weight: 01
|
||||
aliases:
|
||||
- ../../../developers/http_api/authentication/ # /docs/grafana/next/developers/http_api/authentication/
|
||||
---
|
||||
|
||||
# Authentication
|
||||
|
||||
## Authentication options for the HTTP API for Grafana OSS
|
||||
|
||||
{{< docs/shared lookup="developers/authentication.md" source="grafana" version="<GRAFANA_VERSION>" >}}
|
||||
|
||||
## Authentication options for the HTTP API in Grafana Cloud
|
||||
|
||||
{{< docs/shared source="grafana-cloud" lookup="/developer-resources/authentication.md" version="" >}}
|
||||
@@ -0,0 +1,333 @@
|
||||
---
|
||||
aliases:
|
||||
- ../../../http_api/correlations/ # /docs/grafana/next/http_api/correlations/
|
||||
- ../../../developers/http_api/correlations/ # /docs/grafana/next/developers/http_api/correlations/
|
||||
canonical: https://grafana.com/docs/grafana/latest/developer-resources/api-reference/http-api/correlations/
|
||||
description: Grafana Correlations HTTP API
|
||||
keywords:
|
||||
- grafana
|
||||
- http
|
||||
- documentation
|
||||
- api
|
||||
- correlations
|
||||
- Glue
|
||||
labels:
|
||||
products:
|
||||
- enterprise
|
||||
- oss
|
||||
- cloud
|
||||
title: 'Correlations HTTP API '
|
||||
---
|
||||
|
||||
# Correlations API
|
||||
|
||||
This API can be used to define correlations between data sources.
|
||||
|
||||
## Create correlations
|
||||
|
||||
`POST /api/datasources/uid/:sourceUID/correlations`
|
||||
|
||||
Creates a correlation between two data sources - the source data source identified by `sourceUID` in the path, and the target data source which is specified in the body.
|
||||
|
||||
**Example request:**
|
||||
|
||||
```http
|
||||
POST /api/datasources/uid/uyBf2637k/correlations HTTP/1.1
|
||||
Accept: application/json
|
||||
Content-Type: application/json
|
||||
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
|
||||
{
|
||||
```
|
||||
|
||||
JSON body schema:
|
||||
|
||||
- **targetUID** – Target data source uid.
|
||||
- **label** – A label for the correlation.
|
||||
- **description** – A description for the correlation.
|
||||
|
||||
**Example response:**
|
||||
|
||||
```http
|
||||
HTTP/1.1 200
|
||||
Content-Type: application/json
|
||||
{
|
||||
```
|
||||
|
||||
Status codes:
|
||||
|
||||
- **200** – OK
|
||||
- **400** - Errors (invalid JSON, missing or invalid fields)
|
||||
- **401** – Unauthorized
|
||||
- **403** – Forbidden, source data source is read-only
|
||||
- **404** – Not found, either source or target data source could not be found
|
||||
- **500** – Internal error
|
||||
|
||||
## Delete correlations
|
||||
|
||||
`DELETE /api/datasources/uid/:sourceUID/correlations/:correlationUID`
|
||||
|
||||
Deletes a correlation.
|
||||
|
||||
**Example request:**
|
||||
|
||||
```http
|
||||
DELETE /api/datasources/uid/uyBf2637k/correlations/J6gn7d31L HTTP/1.1
|
||||
Accept: application/json
|
||||
Content-Type: application/json
|
||||
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
|
||||
```
|
||||
|
||||
**Example response:**
|
||||
|
||||
```http
|
||||
HTTP/1.1 200
|
||||
Content-Type: application/json
|
||||
{
|
||||
```
|
||||
|
||||
Status codes:
|
||||
|
||||
- **200** – OK
|
||||
- **401** – Unauthorized
|
||||
- **403** – Forbidden, data source is read-only
|
||||
- **404** – Correlation not found
|
||||
- **500** – Internal error
|
||||
|
||||
## Update correlations
|
||||
|
||||
`PATCH /api/datasources/uid/:sourceUID/correlations/:correlationUID`
|
||||
|
||||
Updates a correlation.
|
||||
|
||||
**Example request:**
|
||||
|
||||
```http
|
||||
POST /api/datasources/uid/uyBf2637k/correlations/J6gn7d31L HTTP/1.1
|
||||
Accept: application/json
|
||||
Content-Type: application/json
|
||||
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
|
||||
{
|
||||
```
|
||||
|
||||
JSON body schema:
|
||||
|
||||
- **label** – A label for the correlation.
|
||||
- **description** – A description for the correlation.
|
||||
|
||||
**Example response:**
|
||||
|
||||
```http
|
||||
HTTP/1.1 200
|
||||
Content-Type: application/json
|
||||
{
|
||||
```
|
||||
|
||||
Status codes:
|
||||
|
||||
- **200** – OK
|
||||
- **400** – Bad request
|
||||
- **401** – Unauthorized
|
||||
- **403** – Forbidden, source data source is read-only
|
||||
- **404** – Not found, either source or target data source could not be found
|
||||
- **500** – Internal error
|
||||
|
||||
## Get single correlation
|
||||
|
||||
`GET /api/datasources/uid/:sourceUID/correlations/:correlationUID`
|
||||
|
||||
Gets a single correlation.
|
||||
|
||||
**Example request:**
|
||||
|
||||
```http
|
||||
GET /api/datasources/uid/uyBf2637k/correlations/J6gn7d31L HTTP/1.1
|
||||
Accept: application/json
|
||||
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
|
||||
```
|
||||
|
||||
**Example response:**
|
||||
|
||||
```http
|
||||
HTTP/1.1 200
|
||||
Content-Type: application/json
|
||||
{
|
||||
```
|
||||
|
||||
Status codes:
|
||||
|
||||
- **200** – OK
|
||||
- **401** – Unauthorized
|
||||
- **404** – Not found, either source data source or correlation were not found
|
||||
- **500** – Internal error
|
||||
|
||||
## Get all correlations originating from a given data source
|
||||
|
||||
`GET /api/datasources/uid/:sourceUID/correlations`
|
||||
|
||||
Get all correlations originating from the data source identified by the given `sourceUID` in the path.
|
||||
|
||||
**Example request:**
|
||||
|
||||
```http
|
||||
GET /api/datasources/uid/uyBf2637k/correlations HTTP/1.1
|
||||
Accept: application/json
|
||||
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
|
||||
```
|
||||
|
||||
**Example response:**
|
||||
|
||||
```http
|
||||
HTTP/1.1 200
|
||||
Content-Type: application/json
|
||||
[
|
||||
```
|
||||
|
||||
Status codes:
|
||||
|
||||
- **200** – OK
|
||||
- **401** – Unauthorized
|
||||
- **404** – Not found, either source data source is not found or no correlation exists originating from the given data source
|
||||
- **500** – Internal error
|
||||
|
||||
## Get all correlations
|
||||
|
||||
`GET /api/datasources/correlations`
|
||||
|
||||
Get all correlations.
|
||||
|
||||
Query parameters:
|
||||
|
||||
- **page** - Optional. Specify which page number to return. Use the limit parameter to specify the number of correlations per page. The default is page 1.
|
||||
- **limit** - Optional. Limits the number of returned correlations per page. The default is 100 correlations per page. The maximum limit is 1000 correlations in a page.
|
||||
- **sourceUID** - Optional. Specify a source datasource UID to filter by. This can be repeated to filter by multiple datasources.
|
||||
|
||||
**Example request:**
|
||||
|
||||
```http
|
||||
GET /api/datasources/correlations HTTP/1.1
|
||||
Accept: application/json
|
||||
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
|
||||
```
|
||||
|
||||
**Example response:**
|
||||
|
||||
```http
|
||||
HTTP/1.1 200
|
||||
Content-Type: application/json
|
||||
[
|
||||
```
|
||||
|
||||
Status codes:
|
||||
|
||||
- **200** – OK
|
||||
- **401** – Unauthorized
|
||||
- **404** – Not found, no correlation is found
|
||||
- **500** – Internal error
|
||||
GET /api/datasources/uid/uyBf2637k/correlations HTTP/1.1
|
||||
Accept: application/json
|
||||
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
|
||||
```
|
||||
|
||||
**Example response:**
|
||||
|
||||
```http
|
||||
HTTP/1.1 200
|
||||
Content-Type: application/json
|
||||
[
|
||||
{
|
||||
"description": "Logs to Traces",
|
||||
"label": "My Label",
|
||||
"sourceUID": "uyBf2637k",
|
||||
"targetUID": "PDDA8E780A17E7EF1",
|
||||
"uid": "J6gn7d31L",
|
||||
"provisioned": false,
|
||||
"type": "query",
|
||||
"config": {
|
||||
"field": "message",
|
||||
"target": {},
|
||||
}
|
||||
},
|
||||
{
|
||||
"description": "Logs to Metrics",
|
||||
"label": "Another Label",
|
||||
"sourceUID": "uyBf2637k",
|
||||
"targetUID": "P15396BDD62B2BE29",
|
||||
"uid": "uWCpURgVk",
|
||||
"provisioned": false,
|
||||
"type": "query",
|
||||
"config": {
|
||||
"field": "message",
|
||||
"target": {},
|
||||
}
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
Status codes:
|
||||
|
||||
- **200** – OK
|
||||
- **401** – Unauthorized
|
||||
- **404** – Not found, either source data source is not found or no correlation exists originating from the given data source
|
||||
- **500** – Internal error
|
||||
|
||||
## Get all correlations
|
||||
|
||||
`GET /api/datasources/correlations`
|
||||
|
||||
Get all correlations.
|
||||
|
||||
Query parameters:
|
||||
|
||||
- **page** - Optional. Specify which page number to return. Use the limit parameter to specify the number of correlations per page. The default is page 1.
|
||||
- **limit** - Optional. Limits the number of returned correlations per page. The default is 100 correlations per page. The maximum limit is 1000 correlations in a page.
|
||||
- **sourceUID** - Optional. Specify a source datasource UID to filter by. This can be repeated to filter by multiple datasources.
|
||||
|
||||
**Example request:**
|
||||
|
||||
```http
|
||||
GET /api/datasources/correlations HTTP/1.1
|
||||
Accept: application/json
|
||||
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
|
||||
```
|
||||
|
||||
**Example response:**
|
||||
|
||||
```http
|
||||
HTTP/1.1 200
|
||||
Content-Type: application/json
|
||||
[
|
||||
{
|
||||
"description": "Prometheus to Loki",
|
||||
"label": "My Label",
|
||||
"sourceUID": "uyBf2637k",
|
||||
"targetUID": "PDDA8E780A17E7EF1",
|
||||
"uid": "J6gn7d31L",
|
||||
"provisioned": false,
|
||||
"type": "query",
|
||||
"config": {
|
||||
"field": "message",
|
||||
"target": {},
|
||||
}
|
||||
},
|
||||
{
|
||||
"description": "Loki to Tempo",
|
||||
"label": "Another Label",
|
||||
"sourceUID": "PDDA8E780A17E7EF1",
|
||||
"targetUID": "P15396BDD62B2BE29",
|
||||
"uid": "uWCpURgVk",
|
||||
"provisioned": false,
|
||||
"type": "query",
|
||||
"config": {
|
||||
"field": "message",
|
||||
"target": {},
|
||||
}
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
Status codes:
|
||||
|
||||
- **200** – OK
|
||||
- **401** – Unauthorized
|
||||
- **404** – Not found, no correlation is found
|
||||
- **500** – Internal error
|
||||
1152
docs/sources/developer-resources/api-reference/http-api/dashboard.md
Normal file
1152
docs/sources/developer-resources/api-reference/http-api/dashboard.md
Normal file
File diff suppressed because it is too large
Load Diff
@@ -0,0 +1,187 @@
|
||||
---
|
||||
aliases:
|
||||
- ../../../http_api/dashboard_permissions/ # /docs/grafana/next/http_api/dashboard_permissions/
|
||||
- ../../../http_api/dashboardpermissions/ # /docs/grafana/next/http_api/dashboardpermissions/
|
||||
- ../../../developers/http_api/dashboard_permissions/ # /docs/grafana/next/developers/http_api/dashboard_permissions/
|
||||
canonical: https://grafana.com/docs/grafana/latest/developer-resources/api-reference/http-api/dashboard_permissions/
|
||||
description: Grafana Dashboard Permissions HTTP API
|
||||
keywords:
|
||||
- grafana
|
||||
- http
|
||||
- documentation
|
||||
- api
|
||||
- dashboard
|
||||
- permission
|
||||
- permissions
|
||||
- acl
|
||||
labels:
|
||||
products:
|
||||
- enterprise
|
||||
- oss
|
||||
- cloud
|
||||
title: Dashboard Permissions HTTP API
|
||||
---
|
||||
|
||||
# Dashboard Permissions API
|
||||
|
||||
This API can be used to update/get 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:
|
||||
|
||||
- 1 = View
|
||||
- 2 = Edit
|
||||
- 4 = Admin
|
||||
|
||||
> If you are running Grafana Enterprise, for some endpoints you'll need to have specific permissions. Refer to [Role-based access control permissions](/docs/grafana/latest/administration/roles-and-permissions/access-control/custom-role-actions-scopes/) for more information.
|
||||
|
||||
## Get permissions for a dashboard
|
||||
|
||||
`GET /api/dashboards/uid/:uid/permissions`
|
||||
|
||||
Gets all existing permissions for the dashboard with the given `uid`.
|
||||
|
||||
**Required permissions**
|
||||
|
||||
See note in the [introduction](#dashboard-permission-api) for an explanation.
|
||||
|
||||
<!-- prettier-ignore-start -->
|
||||
| Action | Scope |
|
||||
| ----------------------------- | ------------------------------------------------------------------------------------------------------- |
|
||||
| `dashboards.permissions:read` | <ul><li>`dashboards:*`</li><li>`dashboards:uid:*`</li><li>`folders:*`</li><li>`folders:uid:*`</li></ul> |
|
||||
{ .no-spacing-list }
|
||||
<!-- prettier-ignore-end -->
|
||||
|
||||
**Example request**:
|
||||
|
||||
```http
|
||||
GET /api/dashboards/uid/dHEquNzGz/permissions HTTP/1.1
|
||||
Accept: application/json
|
||||
Content-Type: application/json
|
||||
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
|
||||
```
|
||||
|
||||
**Example Response**
|
||||
|
||||
```http
|
||||
HTTP/1.1 200 OK
|
||||
Content-Type: application/json; charset=UTF-8
|
||||
Content-Length: 551
|
||||
|
||||
```
|
||||
|
||||
Status Codes:
|
||||
|
||||
- **200** - Ok
|
||||
- **401** - Unauthorized
|
||||
- **403** - Access denied
|
||||
- **404** - Dashboard not found
|
||||
|
||||
## Update permissions for a dashboard
|
||||
|
||||
`POST /api/dashboards/uid/:uid/permissions`
|
||||
|
||||
Updates permissions for a dashboard. This operation will remove existing permissions if they're not included in the request.
|
||||
|
||||
**Required permissions**
|
||||
|
||||
See note in the [introduction](#dashboard-permission-api) for an explanation.
|
||||
|
||||
<!-- prettier-ignore-start -->
|
||||
| Action | Scope |
|
||||
| ------------------------------ | ------------------------------------------------------------------------------------------------------- |
|
||||
| `dashboards.permissions:write` | <ul><li>`dashboards:*`</li><li>`dashboards:uid:*`</li><li>`folders:*`</li><li>`folders:uid:*`</li></ul> |
|
||||
{ .no-spacing-list }
|
||||
<!-- prettier-ignore-end -->
|
||||
|
||||
**Example request**:
|
||||
|
||||
```http
|
||||
POST /api/dashboards/uid/dHEquNzGz/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/update. Items that are omitted from the list will be removed.
|
||||
|
||||
**Example response**:
|
||||
|
||||
```http
|
||||
HTTP/1.1 200 OK
|
||||
Content-Type: application/json; charset=UTF-8
|
||||
Content-Length: 35
|
||||
|
||||
```
|
||||
|
||||
Status Codes:
|
||||
|
||||
- **200** - Ok
|
||||
- **401** - Unauthorized
|
||||
- **403** - Access denied
|
||||
- **404** - Dashboard not found
|
||||
"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/update. Items that are omitted from the list will be removed.
|
||||
|
||||
**Example response**:
|
||||
|
||||
```http
|
||||
HTTP/1.1 200 OK
|
||||
Content-Type: application/json; charset=UTF-8
|
||||
Content-Length: 35
|
||||
|
||||
{"message":"Dashboard permissions updated"}
|
||||
```
|
||||
|
||||
Status Codes:
|
||||
|
||||
- **200** - Ok
|
||||
- **401** - Unauthorized
|
||||
- **403** - Access denied
|
||||
- **404** - Dashboard not found
|
||||
@@ -0,0 +1,329 @@
|
||||
---
|
||||
aliases:
|
||||
- ../../../http_api/dashboard_public/ # /docs/grafana/next/http_api/dashboard_public/
|
||||
- ../../../developers/http_api/dashboard_public/ # /docs/grafana/next/developers/http_api/dashboard_public/
|
||||
canonical: https://grafana.com/docs/grafana/latest/developer-resources/api-reference/http-api/dashboard_public/
|
||||
description: Grafana Shared Dashboards HTTP API
|
||||
keywords:
|
||||
- grafana
|
||||
- http
|
||||
- documentation
|
||||
- api
|
||||
- dashboard
|
||||
labels:
|
||||
products:
|
||||
- enterprise
|
||||
- oss
|
||||
- cloud
|
||||
title: Shared Dashboards HTTP API
|
||||
refs:
|
||||
role-based-access-control-permissions:
|
||||
- pattern: /docs/grafana/
|
||||
destination: /docs/grafana/<GRAFANA_VERSION>/administration/roles-and-permissions/access-control/custom-role-actions-scopes/
|
||||
- pattern: /docs/grafana-cloud/
|
||||
destination: /docs/grafana/<GRAFANA_VERSION>/administration/roles-and-permissions/access-control/custom-role-actions-scopes/
|
||||
---
|
||||
|
||||
# Shared Dashboards API
|
||||
|
||||
{{< admonition type="note" >}}
|
||||
|
||||
If you're running Grafana Enterprise, you'll need to have specific permissions for some endpoints. Refer to [Role-based access control permissions](ref:role-based-access-control-permissions) for more information.
|
||||
|
||||
{{< /admonition >}}
|
||||
|
||||
## Create a shared dashboard
|
||||
|
||||
`POST /api/dashboards/uid/:uid/public-dashboards/`
|
||||
|
||||
Creates a new shared dashboard.
|
||||
|
||||
**Required permissions**
|
||||
|
||||
See note in the [introduction](#shared-dashboards-api) for an explanation.
|
||||
|
||||
| Action | Scope |
|
||||
| ------------------------- | -------------------------------- |
|
||||
| `dashboards.public:write` | `dashboards:uid:<dashboard UID>` |
|
||||
|
||||
**Example Request for new shared dashboard**:
|
||||
|
||||
```http
|
||||
POST /api/dashboards/uid/xCpsVuc4z/public-dashboards/ HTTP/1.1
|
||||
Accept: application/json
|
||||
Content-Type: application/json
|
||||
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
|
||||
|
||||
```
|
||||
|
||||
JSON Body schema:
|
||||
|
||||
- **uid** – Optional. Unique identifier when creating a shared dashboard. If it's null, it will generate a new uid.
|
||||
- **accessToken** – Optional. Unique access token. If it's null, it will generate a new access token.
|
||||
- **timeSelectionEnabled** – Optional. Set to `true` to enable the time picker in the shared dashboard. The default value is `false`.
|
||||
- **isEnabled** – Optional. Set to `true` to enable the shared dashboard. The default value is `false`.
|
||||
- **annotationsEnabled** – Optional. Set to `true` to show annotations. The default value is `false`.
|
||||
- **share** – Optional. Set the share mode. The default value is `public`.
|
||||
|
||||
**Example Response**:
|
||||
|
||||
```http
|
||||
HTTP/1.1 200 OK
|
||||
Content-Type: application/json; charset=UTF-8
|
||||
Content-Length: 78
|
||||
|
||||
```
|
||||
|
||||
Status Codes:
|
||||
|
||||
- **200** – Created
|
||||
- **400** – Errors (such as invalid json, missing or invalid fields, or dashboard is shared)
|
||||
- **401** – Unauthorized
|
||||
- **403** – Access denied
|
||||
- **404** – Dashboard not found
|
||||
|
||||
The error response body will have the following properties:
|
||||
|
||||
```http
|
||||
HTTP/1.1 400 Bad request
|
||||
Content-Type: application/json; charset=UTF-8
|
||||
Content-Length: 107
|
||||
|
||||
```
|
||||
|
||||
## Update a shared dashboard
|
||||
|
||||
`PATCH /api/dashboards/uid/:uid/public-dashboards/:publicDashboardUid`
|
||||
|
||||
Will update the shared dashboard given the specified unique identifier (uid).
|
||||
|
||||
**Required permissions**
|
||||
|
||||
See note in the [introduction](#shared-dashboard-api) for an explanation.
|
||||
|
||||
| Action | Scope |
|
||||
| ------------------------- | -------------------------------- |
|
||||
| `dashboards.public:write` | `dashboards:uid:<dashboard UID>` |
|
||||
|
||||
**Example Request for updating a shared dashboard**:
|
||||
|
||||
```http
|
||||
PATCH /api/dashboards/uid/xCpsVuc4z/public-dashboards/cd56d9fd-f3d4-486d-afba-a21760e2acbe HTTP/1.1
|
||||
Accept: application/json
|
||||
Content-Type: application/json
|
||||
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
|
||||
|
||||
```
|
||||
|
||||
JSON Body schema:
|
||||
|
||||
- **timeSelectionEnabled** – Optional. Set to `true` to enable the time picker in the shared dashboard. The default value is `false`.
|
||||
- **isEnabled** – Optional. Set to `true` to enable the shared dashboard. The default value is `false`.
|
||||
- **annotationsEnabled** – Optional. Set to `true` to show annotations. The default value is `false`.
|
||||
- **share** – Optional. Set the share mode. The default value is `public`.
|
||||
|
||||
**Example Response**:
|
||||
|
||||
```http
|
||||
HTTP/1.1 200 OK
|
||||
Content-Type: application/json; charset=UTF-8
|
||||
Content-Length: 78
|
||||
|
||||
```
|
||||
|
||||
Status Codes:
|
||||
|
||||
- **200** – Updated
|
||||
- **400** – Errors (such as invalid json, missing or invalid fields)
|
||||
- **401** – Unauthorized
|
||||
- **403** – Access denied
|
||||
- **404** – Dashboard not found
|
||||
|
||||
The error response body will have the following properties:
|
||||
|
||||
```http
|
||||
HTTP/1.1 400 Bad request
|
||||
Content-Type: application/json; charset=UTF-8
|
||||
Content-Length: 107
|
||||
|
||||
```
|
||||
|
||||
## Get shared dashboard by dashboard uid
|
||||
|
||||
`GET /api/dashboards/uid/:uid/public-dashboards/`
|
||||
|
||||
Will return the shared dashboard given the dashboard unique identifier (uid).
|
||||
|
||||
**Required permissions**
|
||||
|
||||
See note in the [introduction](#shared-dashboard-api) for an explanation.
|
||||
|
||||
| Action | Scope |
|
||||
| ----------------- | -------------------------------- |
|
||||
| `dashboards:read` | `dashboards:uid:<dashboard UID>` |
|
||||
|
||||
**Example Request**:
|
||||
|
||||
```http
|
||||
GET /api/dashboards/uid/xCpsVuc4z/public-dashboards/ HTTP/1.1
|
||||
Accept: application/json
|
||||
Content-Type: application/json
|
||||
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
|
||||
```
|
||||
|
||||
**Example Response**:
|
||||
|
||||
```http
|
||||
HTTP/1.1 200
|
||||
Content-Type: application/json
|
||||
|
||||
```
|
||||
|
||||
Status Codes:
|
||||
|
||||
- **200** – Found
|
||||
- **401** – Unauthorized
|
||||
- **403** – Access denied
|
||||
- **404** – Dashboard not found
|
||||
|
||||
## Delete shared dashboard by dashboard uid and shared dashboard uid
|
||||
|
||||
`DELETE /api/dashboards/uid/:uid/public-dashboards/:publicDashboardUid`
|
||||
|
||||
Will delete the shared dashboard given the specified unique identifier (uid).
|
||||
|
||||
**Required permissions**
|
||||
|
||||
See note in the [introduction](#shared-dashboard-api) for an explanation.
|
||||
|
||||
| Action | Scope |
|
||||
| ------------------------- | -------------------------------- |
|
||||
| `dashboards.public:write` | `dashboards:uid:<dashboard UID>` |
|
||||
|
||||
**Example Request**:
|
||||
|
||||
```http
|
||||
DELETE /api/dashboards/uid/xCpsVuc4z/public-dashboards/cd56d9fd-f3d4-486d-afba-a21760e2acbe HTTP/1.1
|
||||
Accept: application/json
|
||||
Content-Type: application/json
|
||||
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
|
||||
```
|
||||
|
||||
Status Codes:
|
||||
|
||||
- **200** – Deleted
|
||||
- **401** – Unauthorized
|
||||
- **403** – Access denied
|
||||
|
||||
## Get a list of all shared dashboards with pagination
|
||||
|
||||
`GET /api/dashboards/public-dashboards`
|
||||
|
||||
**Required permissions**
|
||||
|
||||
See note in the [introduction](#shared-dashboard-api) for an explanation.
|
||||
|
||||
| Action | Scope |
|
||||
| ----------------- | -------------------------------- |
|
||||
| `dashboards:read` | `dashboards:uid:<dashboard UID>` |
|
||||
|
||||
**Example Request**:
|
||||
|
||||
```http
|
||||
GET /api/dashboards/public-dashboards?perpage=2&page=3 HTTP/1.1
|
||||
Accept: application/json
|
||||
Content-Type: application/json
|
||||
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
|
||||
```
|
||||
|
||||
**Example Response**:
|
||||
|
||||
```http
|
||||
HTTP/1.1 200
|
||||
Content-Type: application/json
|
||||
|
||||
```
|
||||
|
||||
- **200** – Found
|
||||
- **401** – Unauthorized
|
||||
- **403** – Access denied
|
||||
- **404** – Dashboard not found
|
||||
|
||||
## Delete shared dashboard by dashboard uid and shared dashboard uid
|
||||
|
||||
`DELETE /api/dashboards/uid/:uid/public-dashboards/:publicDashboardUid`
|
||||
|
||||
Will delete the shared dashboard given the specified unique identifier (uid).
|
||||
|
||||
**Required permissions**
|
||||
|
||||
See note in the [introduction](#shared-dashboard-api) for an explanation.
|
||||
|
||||
| Action | Scope |
|
||||
| ------------------------- | -------------------------------- |
|
||||
| `dashboards.public:write` | `dashboards:uid:<dashboard UID>` |
|
||||
|
||||
**Example Request**:
|
||||
|
||||
```http
|
||||
DELETE /api/dashboards/uid/xCpsVuc4z/public-dashboards/cd56d9fd-f3d4-486d-afba-a21760e2acbe HTTP/1.1
|
||||
Accept: application/json
|
||||
Content-Type: application/json
|
||||
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
|
||||
```
|
||||
|
||||
Status Codes:
|
||||
|
||||
- **200** – Deleted
|
||||
- **401** – Unauthorized
|
||||
- **403** – Access denied
|
||||
|
||||
## Get a list of all shared dashboards with pagination
|
||||
|
||||
`GET /api/dashboards/public-dashboards`
|
||||
|
||||
**Required permissions**
|
||||
|
||||
See note in the [introduction](#shared-dashboard-api) for an explanation.
|
||||
|
||||
| Action | Scope |
|
||||
| ----------------- | -------------------------------- |
|
||||
| `dashboards:read` | `dashboards:uid:<dashboard UID>` |
|
||||
|
||||
**Example Request**:
|
||||
|
||||
```http
|
||||
GET /api/dashboards/public-dashboards?perpage=2&page=3 HTTP/1.1
|
||||
Accept: application/json
|
||||
Content-Type: application/json
|
||||
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
|
||||
```
|
||||
|
||||
**Example Response**:
|
||||
|
||||
```http
|
||||
HTTP/1.1 200
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"publicDashboards": [
|
||||
{
|
||||
"uid": "e9f29a3c-fcc3-4fc5-a690-ae39c97d24ba",
|
||||
"accessToken": "6c13ec1997ba48c5af8c9c5079049692",
|
||||
"title": "Datasource Shared Queries",
|
||||
"dashboardUid": "d2f21d0a-76c7-47ec-b5f3-9dda16e5a996",
|
||||
"isEnabled": true
|
||||
},
|
||||
{
|
||||
"uid": "a174f604-6fe7-47de-97b4-48b7e401b540",
|
||||
"accessToken": "d1fcff345c0f45e8a78c096c9696034a",
|
||||
"title": "Datasource with template variables",
|
||||
"dashboardUid": "51DiOw0Vz",
|
||||
"isEnabled": true
|
||||
}
|
||||
],
|
||||
"totalCount": 30,
|
||||
"page": 3,
|
||||
"perPage": 2
|
||||
}
|
||||
```
|
||||
@@ -0,0 +1,316 @@
|
||||
---
|
||||
aliases:
|
||||
- ../../../http_api/dashboard_versions/ # /docs/grafana/next/http_api/dashboard_versions/
|
||||
- ../../../http_api/dashboardversions/ # /docs/grafana/next/http_api/dashboardversions/
|
||||
- ../../../developers/http_api/dashboard_versions/ # /docs/grafana/next/developers/http_api/dashboard_versions/
|
||||
canonical: https://grafana.com/docs/grafana/latest/developer-resources/api-reference/http-api/dashboard_versions/
|
||||
description: Grafana Dashboard Versions HTTP API
|
||||
keywords:
|
||||
- grafana
|
||||
- http
|
||||
- documentation
|
||||
- api
|
||||
- dashboard
|
||||
- versions
|
||||
labels:
|
||||
products:
|
||||
- enterprise
|
||||
- oss
|
||||
- cloud
|
||||
title: 'Dashboard Versions HTTP API '
|
||||
---
|
||||
|
||||
# Dashboard Versions
|
||||
|
||||
## Get all dashboard versions by dashboard UID
|
||||
|
||||
Query parameters:
|
||||
|
||||
- **limit** - Maximum number of results to return. Defaults to 1000 if not set, or if an invalid value is passed in.
|
||||
- **start** - Version to start from when returning queries
|
||||
|
||||
`GET /api/dashboards/uid/:uid/versions`
|
||||
|
||||
Gets all existing dashboard versions for the dashboard with the given `uid`.
|
||||
|
||||
**Example request for getting all dashboard versions**:
|
||||
|
||||
```http
|
||||
GET /api/dashboards/uid/QA7wKklGz/versions?limit=2?start=0 HTTP/1.1
|
||||
Accept: application/json
|
||||
Content-Type: application/json
|
||||
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
|
||||
```
|
||||
|
||||
**Example Response**
|
||||
|
||||
```http
|
||||
HTTP/1.1 200 OK
|
||||
Content-Type: application/json; charset=UTF-8
|
||||
Content-Length: 428
|
||||
|
||||
```
|
||||
|
||||
Status Codes:
|
||||
|
||||
- **200** - Ok
|
||||
- **400** - Errors
|
||||
- **401** - Unauthorized
|
||||
- **404** - Dashboard version not found
|
||||
|
||||
## Get dashboard version by dashboard UID
|
||||
|
||||
`GET /api/dashboards/uid/:uid/versions/:version`
|
||||
|
||||
Get the dashboard version with the given version, for the dashboard with the given UID.
|
||||
|
||||
**Example request for getting a dashboard version**:
|
||||
|
||||
```http
|
||||
GET /api/dashboards/uid/QA7wKklGz/versions/1 HTTP/1.1
|
||||
Accept: application/json
|
||||
Content-Type: application/json
|
||||
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
|
||||
```
|
||||
|
||||
**Example response**:
|
||||
|
||||
```http
|
||||
HTTP/1.1 200 OK
|
||||
Content-Type: application/json; charset=UTF-8
|
||||
Content-Length: 1300
|
||||
|
||||
```
|
||||
|
||||
Status Codes:
|
||||
|
||||
- **200** - Ok
|
||||
- **401** - Unauthorized
|
||||
- **404** - Dashboard version not found
|
||||
|
||||
## Restore dashboard by dashboard UID
|
||||
|
||||
`POST /api/dashboards/uid/:uid/restore`
|
||||
|
||||
Restores a dashboard to a given dashboard version using `uid`.
|
||||
|
||||
**Example request for restoring a dashboard version**:
|
||||
|
||||
```http
|
||||
POST /api/dashboards/uid/QA7wKklGz/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
|
||||
HTTP/1.1 200 OK
|
||||
Content-Type: application/json; charset=UTF-8
|
||||
Content-Length: 67
|
||||
|
||||
```
|
||||
|
||||
JSON response body schema:
|
||||
|
||||
- **slug** - the URL friendly slug of the dashboard's title
|
||||
- **status** - whether the restoration was successful or not
|
||||
- **version** - the new dashboard version, following the restoration
|
||||
|
||||
Status codes:
|
||||
|
||||
- **200** - OK
|
||||
- **400** - Bad request (specified version has the same content as the current dashboard)
|
||||
- **401** - Unauthorized
|
||||
- **404** - Not found (dashboard not found or dashboard version not found)
|
||||
- **500** - Internal server error (indicates issue retrieving dashboard tags from database)
|
||||
|
||||
**Example error response**
|
||||
|
||||
```http
|
||||
HTTP/1.1 404 Not Found
|
||||
Content-Type: application/json; charset=UTF-8
|
||||
Content-Length: 46
|
||||
|
||||
```
|
||||
|
||||
JSON response body schema:
|
||||
|
||||
- **message** - Message explaining the reason for the request failure.
|
||||
|
||||
## Compare dashboard versions
|
||||
|
||||
`POST /api/dashboards/calculate-diff`
|
||||
|
||||
Compares two dashboard versions by calculating the JSON diff of them.
|
||||
|
||||
**Example request**:
|
||||
|
||||
```http
|
||||
POST /api/dashboards/calculate-diff HTTP/1.1
|
||||
Accept: text/html
|
||||
Content-Type: application/json
|
||||
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
|
||||
|
||||
```
|
||||
|
||||
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. Can be "json" or "basic".
|
||||
|
||||
**Example response (JSON diff)**:
|
||||
|
||||
```http
|
||||
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
|
||||
- **400** - Bad request (invalid JSON sent)
|
||||
- **401** - Unauthorized
|
||||
- **404** - Not found
|
||||
|
||||
**Example response (basic diff)**:
|
||||
|
||||
```http
|
||||
HTTP/1.1 200 OK
|
||||
Content-Type: text/html; charset=UTF-8
|
||||
|
||||
```
|
||||
|
||||
The response here is a summary of the changes, derived from the diff between the two JSON objects.
|
||||
|
||||
Status Codes:
|
||||
|
||||
- **200** - OK
|
||||
- **400** - Bad request (invalid JSON sent)
|
||||
- **401** - Unauthorized
|
||||
- **404** - Not found
|
||||
{
|
||||
"id": 70,
|
||||
"slug": "my-dashboard",
|
||||
"status": "success",
|
||||
"uid": "QA7wKklGz",
|
||||
"url": "/d/QA7wKklGz/my-dashboard",
|
||||
"version": 3
|
||||
}
|
||||
```
|
||||
|
||||
JSON response body schema:
|
||||
|
||||
- **slug** - the URL friendly slug of the dashboard's title
|
||||
- **status** - whether the restoration was successful or not
|
||||
- **version** - the new dashboard version, following the restoration
|
||||
|
||||
Status codes:
|
||||
|
||||
- **200** - OK
|
||||
- **400** - Bad request (specified version has the same content as the current dashboard)
|
||||
- **401** - Unauthorized
|
||||
- **404** - Not found (dashboard not found or dashboard version not found)
|
||||
- **500** - Internal server error (indicates issue retrieving dashboard tags from database)
|
||||
|
||||
**Example error response**
|
||||
|
||||
```http
|
||||
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** - Message explaining the reason for the request failure.
|
||||
|
||||
## Compare dashboard versions
|
||||
|
||||
`POST /api/dashboards/calculate-diff`
|
||||
|
||||
Compares two dashboard versions by calculating the JSON diff of them.
|
||||
|
||||
**Example request**:
|
||||
|
||||
```http
|
||||
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. Can be "json" or "basic".
|
||||
|
||||
**Example response (JSON diff)**:
|
||||
|
||||
```http
|
||||
HTTP/1.1 200 OK
|
||||
Content-Type: text/html; charset=UTF-8
|
||||
|
||||
<p id="l1" class="diff-line diff-json-same">
|
||||
<!-- Diff omitted -->
|
||||
</p>
|
||||
```
|
||||
|
||||
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
|
||||
- **400** - Bad request (invalid JSON sent)
|
||||
- **401** - Unauthorized
|
||||
- **404** - Not found
|
||||
|
||||
**Example response (basic diff)**:
|
||||
|
||||
```http
|
||||
HTTP/1.1 200 OK
|
||||
Content-Type: text/html; charset=UTF-8
|
||||
|
||||
<div class="diff-group">
|
||||
<!-- Diff omitted -->
|
||||
</div>
|
||||
```
|
||||
|
||||
The response here is a summary of the changes, derived from the diff between the two JSON objects.
|
||||
|
||||
Status Codes:
|
||||
|
||||
- **200** - OK
|
||||
- **400** - Bad request (invalid JSON sent)
|
||||
- **401** - Unauthorized
|
||||
- **404** - Not found
|
||||
@@ -0,0 +1,993 @@
|
||||
---
|
||||
aliases:
|
||||
- ../../../http_api/data_source/ # /docs/grafana/next/http_api/data_source/
|
||||
- ../../../http_api/datasource/ # /docs/grafana/next/http_api/datasource/
|
||||
- ../../../developers/http_api/data_source/ # /docs/grafana/next/developers/http_api/data_source/
|
||||
canonical: https://grafana.com/docs/grafana/latest/developer-resources/api-reference/http-api/data_source/
|
||||
description: Grafana Data source HTTP API
|
||||
keywords:
|
||||
- grafana
|
||||
- http
|
||||
- documentation
|
||||
- api
|
||||
- data source
|
||||
labels:
|
||||
products:
|
||||
- enterprise
|
||||
- oss
|
||||
- cloud
|
||||
title: Data source HTTP API
|
||||
---
|
||||
|
||||
# Data source API
|
||||
|
||||
> If you are running Grafana Enterprise, for some endpoints you'll need to have specific permissions. Refer to [Role-based access control permissions](/docs/grafana/latest/administration/roles-and-permissions/access-control/custom-role-actions-scopes/) for more information.
|
||||
|
||||
## Get all data sources
|
||||
|
||||
`GET /api/datasources`
|
||||
|
||||
{{< admonition type="warning" >}}
|
||||
This API currently doesn't handle pagination. The default maximum number of data sources returned is 5000. You can change this value in the default.ini file.
|
||||
{{< /admonition >}}
|
||||
|
||||
**Required permissions**
|
||||
|
||||
See note in the [introduction](#data-source-api) for an explanation.
|
||||
|
||||
| Action | Scope |
|
||||
| ---------------- | -------------- |
|
||||
| datasources:read | datasources:\* |
|
||||
|
||||
### Examples
|
||||
|
||||
**Example Request**:
|
||||
|
||||
```http
|
||||
GET /api/datasources HTTP/1.1
|
||||
Accept: application/json
|
||||
Content-Type: application/json
|
||||
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
|
||||
```
|
||||
|
||||
**Example Response**:
|
||||
|
||||
```http
|
||||
HTTP/1.1 200
|
||||
Content-Type: application/json
|
||||
|
||||
```
|
||||
|
||||
## Get a single data source by id
|
||||
|
||||
`GET /api/datasources/:datasourceId`
|
||||
|
||||
{{< admonition type="warning" >}}
|
||||
This API is deprecated since Grafana v9.0.0 and will be removed in a future release. Refer to the [API for getting a single data source by UID](#get-a-single-data-source-by-uid) or to the [API for getting a single data source by its name](#get-a-single-data-source-by-name).
|
||||
{{< /admonition >}}
|
||||
|
||||
**Required permissions**
|
||||
|
||||
See note in the [introduction](#data-source-api) for an explanation.
|
||||
|
||||
| Action | Scope |
|
||||
| ---------------- | ---------------------------------------------------------------------------- |
|
||||
| datasources:read | datasources:\*<br>datasources:id:\*<br>datasources:id:1 (single data source) |
|
||||
|
||||
### Examples
|
||||
|
||||
**Example Request**:
|
||||
|
||||
```http
|
||||
GET /api/datasources/1 HTTP/1.1
|
||||
Accept: application/json
|
||||
Content-Type: application/json
|
||||
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
|
||||
```
|
||||
|
||||
**Example Response**:
|
||||
|
||||
```http
|
||||
HTTP/1.1 200
|
||||
Content-Type: application/json
|
||||
|
||||
```
|
||||
|
||||
## Get a single data source by uid
|
||||
|
||||
`GET /api/datasources/uid/:uid`
|
||||
|
||||
**Required permissions**
|
||||
|
||||
See note in the [introduction](#data-source-api) for an explanation.
|
||||
|
||||
| Action | Scope |
|
||||
| ---------------- | -------------------------------------------------------------------------------------- |
|
||||
| datasources:read | datasources:\*<br>datasources:uid:\*<br>datasources:uid:kLtEtcRGk (single data source) |
|
||||
|
||||
### Examples
|
||||
|
||||
**Example request:**
|
||||
|
||||
```http
|
||||
GET /api/datasources/uid/kLtEtcRGk HTTP/1.1
|
||||
Accept: application/json
|
||||
Content-Type: application/json
|
||||
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
|
||||
```
|
||||
|
||||
**Example Response**:
|
||||
|
||||
```http
|
||||
HTTP/1.1 200
|
||||
Content-Type: application/json
|
||||
|
||||
```
|
||||
|
||||
## Get a single data source by name
|
||||
|
||||
`GET /api/datasources/name/:name`
|
||||
|
||||
**Required permissions**
|
||||
|
||||
See note in the [introduction](#data-source-api) for an explanation.
|
||||
|
||||
| Action | Scope |
|
||||
| ---------------- | ---------------------------------------------------------------------------------------------- |
|
||||
| datasources:read | datasources:\*<br>datasources:name:\*<br>datasources:name:test_datasource (single data source) |
|
||||
|
||||
### Examples
|
||||
|
||||
**Example Request**:
|
||||
|
||||
```http
|
||||
GET /api/datasources/name/test_datasource HTTP/1.1
|
||||
Accept: application/json
|
||||
Content-Type: application/json
|
||||
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
|
||||
```
|
||||
|
||||
**Example Response**:
|
||||
|
||||
```http
|
||||
HTTP/1.1 200
|
||||
Content-Type: application/json
|
||||
|
||||
```
|
||||
|
||||
## Get data source Id by name
|
||||
|
||||
`GET /api/datasources/id/:name`
|
||||
|
||||
**Required permissions**
|
||||
|
||||
See note in the [introduction](#data-source-api) for an explanation.
|
||||
|
||||
| Action | Scope |
|
||||
| ------------------- | ---------------------------------------------------------------------------------------------- |
|
||||
| datasources.id:read | datasources:\*<br>datasources:name:\*<br>datasources:name:test_datasource (single data source) |
|
||||
|
||||
### Examples
|
||||
|
||||
**Example Request**:
|
||||
|
||||
```http
|
||||
GET /api/datasources/id/test_datasource HTTP/1.1
|
||||
Accept: application/json
|
||||
Content-Type: application/json
|
||||
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
|
||||
```
|
||||
|
||||
**Example Response**:
|
||||
|
||||
```http
|
||||
HTTP/1.1 200
|
||||
Content-Type: application/json
|
||||
|
||||
```
|
||||
|
||||
## Create a data source
|
||||
|
||||
`POST /api/datasources`
|
||||
|
||||
**Required permissions**
|
||||
|
||||
See note in the [introduction](#data-source-api) for an explanation.
|
||||
|
||||
| Action | Scope |
|
||||
| ------------------ | ----- |
|
||||
| datasources:create | n/a |
|
||||
|
||||
### Examples
|
||||
|
||||
**Example Graphite Request**:
|
||||
|
||||
```http
|
||||
POST /api/datasources HTTP/1.1
|
||||
Accept: application/json
|
||||
Content-Type: application/json
|
||||
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
|
||||
|
||||
```
|
||||
|
||||
**Example Graphite Response**:
|
||||
|
||||
```http
|
||||
HTTP/1.1 200
|
||||
Content-Type: application/json
|
||||
|
||||
```
|
||||
|
||||
{{< admonition type="note" >}}
|
||||
By defining `password` and `basicAuthPassword` under `secureJsonData` Grafana encrypts them securely as an encrypted blob in the database. The response then lists the encrypted fields under `secureJsonFields`.
|
||||
{{< /admonition >}}
|
||||
|
||||
**Example Graphite Request with basic auth enabled**:
|
||||
|
||||
```http
|
||||
POST /api/datasources HTTP/1.1
|
||||
Accept: application/json
|
||||
Content-Type: application/json
|
||||
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
|
||||
|
||||
```
|
||||
|
||||
**Example Response with basic auth enabled**:
|
||||
|
||||
```http
|
||||
HTTP/1.1 200
|
||||
Content-Type: application/json
|
||||
|
||||
```
|
||||
|
||||
**Example CloudWatch Request**:
|
||||
|
||||
```http
|
||||
POST /api/datasources HTTP/1.1
|
||||
Accept: application/json
|
||||
Content-Type: application/json
|
||||
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
|
||||
|
||||
```
|
||||
|
||||
## Update an existing data source by id
|
||||
|
||||
`PUT /api/datasources/:datasourceId`
|
||||
|
||||
{{< admonition type="warning" >}}
|
||||
This API is deprecated since Grafana v9.0.0 and will be removed in a future release. Refer to the [new data source update API](#update-an-existing-data-source).
|
||||
{{< /admonition >}}
|
||||
|
||||
**Required permissions**
|
||||
|
||||
See note in the [introduction](#data-source-api) for an explanation.
|
||||
|
||||
| Action | Scope |
|
||||
| ----------------- | ---------------------------------------------------------------------------- |
|
||||
| datasources:write | datasources:\*<br>datasources:id:\*<br>datasources:id:1 (single data source) |
|
||||
|
||||
### Examples
|
||||
|
||||
**Example Request**:
|
||||
|
||||
```http
|
||||
PUT /api/datasources/1 HTTP/1.1
|
||||
Accept: application/json
|
||||
Content-Type: application/json
|
||||
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
|
||||
|
||||
```
|
||||
|
||||
Note that the UID cannot be modified.
|
||||
|
||||
**Example Response**:
|
||||
|
||||
```http
|
||||
HTTP/1.1 200
|
||||
Content-Type: application/json
|
||||
|
||||
```
|
||||
|
||||
{{< admonition type="note" >}}
|
||||
Similar to [creating a data source](#create-a-data-source), `password` and `basicAuthPassword` should be defined under `secureJsonData` in order to be stored securely as an encrypted blob in the database. Then, the encrypted fields are listed under `secureJsonFields` section in the response.
|
||||
{{< /admonition >}}
|
||||
|
||||
## Update an existing data source
|
||||
|
||||
`PUT /api/datasources/uid/:uid`
|
||||
|
||||
**Required permissions**
|
||||
|
||||
See note in the [introduction](#data-source-api) for an explanation.
|
||||
|
||||
| Action | Scope |
|
||||
| ----------------- | -------------------------------------------------------------------------------------- |
|
||||
| datasources:write | datasources:\*<br>datasources:uid:\*<br>datasources:uid:kLtEtcRGk (single data source) |
|
||||
|
||||
### Examples
|
||||
|
||||
**Example Request**:
|
||||
|
||||
```http
|
||||
PUT /api/datasources/uid/kLtEtcRGk HTTP/1.1
|
||||
Accept: application/json
|
||||
Content-Type: application/json
|
||||
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
|
||||
|
||||
```
|
||||
|
||||
Note that the UID cannot be modified.
|
||||
|
||||
**Example Response**:
|
||||
|
||||
```http
|
||||
HTTP/1.1 200
|
||||
Content-Type: application/json
|
||||
|
||||
```
|
||||
|
||||
{{< admonition type="note" >}}
|
||||
Similar to [creating a data source](#create-a-data-source), `password` and `basicAuthPassword` should be defined under `secureJsonData` in order to be stored securely as an encrypted blob in the database. Then, the encrypted fields are listed under `secureJsonFields` section in the response.
|
||||
{{< /admonition >}}
|
||||
|
||||
## Delete an existing data source by id
|
||||
|
||||
`DELETE /api/datasources/:datasourceId`
|
||||
|
||||
{{< admonition type="warning" >}}
|
||||
This API is deprecated since Grafana v9.0.0 and will be removed in a future release. Refer to the [API for deleting an existing data source by UID](#delete-an-existing-data-source-by-uid) or to the [API for deleting an existing data source by its name](#delete-an-existing-data-source-by-name)
|
||||
{{< /admonition >}}
|
||||
|
||||
**Required permissions**
|
||||
|
||||
See note in the [introduction](#data-source-api) for an explanation.
|
||||
|
||||
| Action | Scope |
|
||||
| ------------------ | ---------------------------------------------------------------------------- |
|
||||
| datasources:delete | datasources:\*<br>datasources:id:\*<br>datasources:id:1 (single data source) |
|
||||
|
||||
### Examples
|
||||
|
||||
**Example Request**:
|
||||
|
||||
```http
|
||||
DELETE /api/datasources/1 HTTP/1.1
|
||||
Accept: application/json
|
||||
Content-Type: application/json
|
||||
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
|
||||
```
|
||||
|
||||
**Example Response**:
|
||||
|
||||
```http
|
||||
HTTP/1.1 200
|
||||
Content-Type: application/json
|
||||
|
||||
```
|
||||
|
||||
## Delete an existing data source by uid
|
||||
|
||||
`DELETE /api/datasources/uid/:uid`
|
||||
|
||||
**Required permissions**
|
||||
|
||||
See note in the [introduction](#data-source-api) for an explanation.
|
||||
|
||||
| Action | Scope |
|
||||
| ------------------ | -------------------------------------------------------------------------------------- |
|
||||
| datasources:delete | datasources:\*<br>datasources:uid:\*<br>datasources:uid:kLtEtcRGk (single data source) |
|
||||
|
||||
### Examples
|
||||
|
||||
**Example request:**
|
||||
|
||||
```http
|
||||
DELETE /api/datasources/uid/kLtEtcRGk HTTP/1.1
|
||||
Accept: application/json
|
||||
Content-Type: application/json
|
||||
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
|
||||
```
|
||||
|
||||
**Example response**:
|
||||
|
||||
```http
|
||||
HTTP/1.1 200
|
||||
Content-Type: application/json
|
||||
|
||||
```
|
||||
|
||||
## Delete an existing data source by name
|
||||
|
||||
`DELETE /api/datasources/name/:datasourceName`
|
||||
|
||||
**Required permissions**
|
||||
|
||||
See note in the [introduction](#data-source-api) for an explanation.
|
||||
|
||||
| Action | Scope |
|
||||
| ------------------ | ---------------------------------------------------------------------------------------------- |
|
||||
| datasources:delete | datasources:\*<br>datasources:name:\*<br>datasources:name:test_datasource (single data source) |
|
||||
|
||||
### Examples
|
||||
|
||||
**Example Request**:
|
||||
|
||||
```http
|
||||
DELETE /api/datasources/name/test_datasource HTTP/1.1
|
||||
Accept: application/json
|
||||
Content-Type: application/json
|
||||
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
|
||||
```
|
||||
|
||||
**Example Response**:
|
||||
|
||||
```http
|
||||
HTTP/1.1 200
|
||||
Content-Type: application/json
|
||||
|
||||
```
|
||||
|
||||
## Data source proxy calls by id
|
||||
|
||||
{{< admonition type="warning" >}}
|
||||
This API is deprecated since Grafana v9.0.0 and will be removed in a future release. Refer to the [new data source API for proxying requests](#data-source-proxy-calls).
|
||||
{{< /admonition >}}
|
||||
|
||||
`GET /api/datasources/proxy/:datasourceId/*`
|
||||
|
||||
Proxies all calls to the actual data source identified by the `datasourceId`.
|
||||
|
||||
## Data source proxy calls
|
||||
|
||||
`GET /api/datasources/proxy/uid/:uid/*`
|
||||
|
||||
Proxies all calls to the actual data source identified by the `uid`.
|
||||
|
||||
## Check data source health by id
|
||||
|
||||
> **Warning:** This API is deprecated since Grafana v9.0.0 and will be removed in a future release. Refer to the [new data source health check API](#check-data-source-health).
|
||||
|
||||
`GET /api/datasources/:datasourceId/health`
|
||||
|
||||
Makes a call to the health endpoint of data source identified by the given `datasourceId`. This is not mandatory - every plugin author has to <a href="https://grafana.com/tutorials/build-a-data-source-backend-plugin/#add-support-for-health-checks" target="_blank">implement support for health checks</a> in their plugin themselves.
|
||||
|
||||
### Examples
|
||||
|
||||
**Example Request**:
|
||||
|
||||
```http
|
||||
GET api/datasources/112/health HTTP/1.1
|
||||
Accept: application/json
|
||||
Content-Type: application/json
|
||||
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
|
||||
```
|
||||
|
||||
**Example Response**:
|
||||
|
||||
```http
|
||||
HTTP/1.1 200
|
||||
Content-Type: application/json
|
||||
|
||||
```
|
||||
|
||||
## Check data source health
|
||||
|
||||
`GET /api/datasources/uid/:uid/health`
|
||||
|
||||
Makes a call to the health endpoint of data source identified by the given `uid`. This is not mandatory - every plugin author has to <a href="https://grafana.com/tutorials/build-a-data-source-backend-plugin/#add-support-for-health-checks" target="_blank">implement support for health checks</a> in their plugin themselves.
|
||||
|
||||
### Examples
|
||||
|
||||
**Example Request**:
|
||||
|
||||
```http
|
||||
GET api/datasources/uid/P8045C56BDA891CB2/health HTTP/1.1
|
||||
Accept: application/json
|
||||
Content-Type: application/json
|
||||
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
|
||||
```
|
||||
|
||||
**Example Response**:
|
||||
|
||||
```http
|
||||
HTTP/1.1 200
|
||||
Content-Type: application/json
|
||||
|
||||
```
|
||||
|
||||
## Fetch data source resources by id
|
||||
|
||||
{{< admonition type="warning" >}}
|
||||
This API is deprecated since Grafana v9.0.0 and will be removed in a future release. Refer to the [new data source resources API](#fetch-data-source-resources).
|
||||
{{< /admonition >}}
|
||||
|
||||
`GET /api/datasources/:datasourceId/resources/*`
|
||||
|
||||
Makes a call to the resources endpoint of data source identified by the given `dashboardId`.
|
||||
|
||||
### Examples
|
||||
|
||||
**Example Request**:
|
||||
|
||||
```http
|
||||
GET api/datasources/112/resources/dimension-keys?region=us-east-2&namespace=AWS%2FEC2&dimensionFilters=%7B%7D&metricName=CPUUtilization HTTP/1.1
|
||||
Accept: application/json
|
||||
Content-Type: application/json
|
||||
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
|
||||
```
|
||||
|
||||
**Example Response**:
|
||||
|
||||
```http
|
||||
HTTP/1.1 200
|
||||
Content-Type: application/json
|
||||
|
||||
```
|
||||
|
||||
## Fetch data source resources
|
||||
|
||||
`GET /api/datasources/uid/:uid/resources/*`
|
||||
|
||||
Makes a call to the resources endpoint of data source identified by the given `uid`.
|
||||
|
||||
### Examples
|
||||
|
||||
**Example Request**:
|
||||
|
||||
```http
|
||||
GET api/datasources/uid/P8045C56BDA891CB2/resources/dimension-keys?region=us-east-2&namespace=AWS%2FEC2&dimensionFilters=%7B%7D&metricName=CPUUtilization HTTP/1.1
|
||||
Accept: application/json
|
||||
Content-Type: application/json
|
||||
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
|
||||
```
|
||||
|
||||
**Example Response**:
|
||||
|
||||
```http
|
||||
HTTP/1.1 200
|
||||
Content-Type: application/json
|
||||
|
||||
```
|
||||
|
||||
## Query a data source
|
||||
|
||||
Queries a data source having a backend implementation.
|
||||
|
||||
`POST /api/ds/query`
|
||||
|
||||
{{< admonition type="note" >}}
|
||||
Grafana's built-in data sources usually have a backend implementation.
|
||||
{{< /admonition >}}
|
||||
|
||||
**Example request for the Test data source**:
|
||||
|
||||
```http
|
||||
POST /api/ds/query HTTP/1.1
|
||||
Accept: application/json
|
||||
Content-Type: application/json
|
||||
|
||||
```
|
||||
|
||||
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:**
|
||||
|
||||
```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]
|
||||
]
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### Status codes
|
||||
|
||||
| Code | Description |
|
||||
| ---- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| 200 | All data source queries returned a successful response. |
|
||||
| 400 | Bad request due to invalid JSON, missing content type, missing or invalid fields, etc. Or one or more data source queries were unsuccessful. Refer to the body for more details. |
|
||||
| 403 | Access denied. |
|
||||
| 404 | Either the data source or plugin required to fulfil the request could not be found. |
|
||||
| 500 | Unexpected error. Refer to the body and/or server logs for more details. |
|
||||
|
||||
**Example Request**:
|
||||
|
||||
```http
|
||||
DELETE /api/datasources/1 HTTP/1.1
|
||||
Accept: application/json
|
||||
Content-Type: application/json
|
||||
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
|
||||
```
|
||||
|
||||
**Example Response**:
|
||||
|
||||
```http
|
||||
HTTP/1.1 200
|
||||
Content-Type: application/json
|
||||
|
||||
{"message":"Data source deleted"}
|
||||
```
|
||||
|
||||
## Delete an existing data source by uid
|
||||
|
||||
`DELETE /api/datasources/uid/:uid`
|
||||
|
||||
**Required permissions**
|
||||
|
||||
See note in the [introduction](#data-source-api) for an explanation.
|
||||
|
||||
| Action | Scope |
|
||||
| ------------------ | -------------------------------------------------------------------------------------- |
|
||||
| datasources:delete | datasources:\*<br>datasources:uid:\*<br>datasources:uid:kLtEtcRGk (single data source) |
|
||||
|
||||
### Examples
|
||||
|
||||
**Example request:**
|
||||
|
||||
```http
|
||||
DELETE /api/datasources/uid/kLtEtcRGk HTTP/1.1
|
||||
Accept: application/json
|
||||
Content-Type: application/json
|
||||
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
|
||||
```
|
||||
|
||||
**Example response**:
|
||||
|
||||
```http
|
||||
HTTP/1.1 200
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"message": "Data source deleted",
|
||||
"id": 1
|
||||
}
|
||||
```
|
||||
|
||||
## Delete an existing data source by name
|
||||
|
||||
`DELETE /api/datasources/name/:datasourceName`
|
||||
|
||||
**Required permissions**
|
||||
|
||||
See note in the [introduction](#data-source-api) for an explanation.
|
||||
|
||||
| Action | Scope |
|
||||
| ------------------ | ---------------------------------------------------------------------------------------------- |
|
||||
| datasources:delete | datasources:\*<br>datasources:name:\*<br>datasources:name:test_datasource (single data source) |
|
||||
|
||||
### Examples
|
||||
|
||||
**Example Request**:
|
||||
|
||||
```http
|
||||
DELETE /api/datasources/name/test_datasource HTTP/1.1
|
||||
Accept: application/json
|
||||
Content-Type: application/json
|
||||
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
|
||||
```
|
||||
|
||||
**Example Response**:
|
||||
|
||||
```http
|
||||
HTTP/1.1 200
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"message":"Data source deleted",
|
||||
"id": 1
|
||||
}
|
||||
```
|
||||
|
||||
## Data source proxy calls by id
|
||||
|
||||
{{< admonition type="warning" >}}
|
||||
This API is deprecated since Grafana v9.0.0 and will be removed in a future release. Refer to the [new data source API for proxying requests](#data-source-proxy-calls).
|
||||
{{< /admonition >}}
|
||||
|
||||
`GET /api/datasources/proxy/:datasourceId/*`
|
||||
|
||||
Proxies all calls to the actual data source identified by the `datasourceId`.
|
||||
|
||||
## Data source proxy calls
|
||||
|
||||
`GET /api/datasources/proxy/uid/:uid/*`
|
||||
|
||||
Proxies all calls to the actual data source identified by the `uid`.
|
||||
|
||||
## Check data source health by id
|
||||
|
||||
> **Warning:** This API is deprecated since Grafana v9.0.0 and will be removed in a future release. Refer to the [new data source health check API](#check-data-source-health).
|
||||
|
||||
`GET /api/datasources/:datasourceId/health`
|
||||
|
||||
Makes a call to the health endpoint of data source identified by the given `datasourceId`. This is not mandatory - every plugin author has to <a href="https://grafana.com/tutorials/build-a-data-source-backend-plugin/#add-support-for-health-checks" target="_blank">implement support for health checks</a> in their plugin themselves.
|
||||
|
||||
### Examples
|
||||
|
||||
**Example Request**:
|
||||
|
||||
```http
|
||||
GET api/datasources/112/health HTTP/1.1
|
||||
Accept: application/json
|
||||
Content-Type: application/json
|
||||
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
|
||||
```
|
||||
|
||||
**Example Response**:
|
||||
|
||||
```http
|
||||
HTTP/1.1 200
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"message": "1. Successfully queried the CloudWatch metrics API.\n2. Successfully queried the CloudWatch logs API.",
|
||||
"status": "OK"
|
||||
}
|
||||
```
|
||||
|
||||
## Check data source health
|
||||
|
||||
`GET /api/datasources/uid/:uid/health`
|
||||
|
||||
Makes a call to the health endpoint of data source identified by the given `uid`. This is not mandatory - every plugin author has to <a href="https://grafana.com/tutorials/build-a-data-source-backend-plugin/#add-support-for-health-checks" target="_blank">implement support for health checks</a> in their plugin themselves.
|
||||
|
||||
### Examples
|
||||
|
||||
**Example Request**:
|
||||
|
||||
```http
|
||||
GET api/datasources/uid/P8045C56BDA891CB2/health HTTP/1.1
|
||||
Accept: application/json
|
||||
Content-Type: application/json
|
||||
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
|
||||
```
|
||||
|
||||
**Example Response**:
|
||||
|
||||
```http
|
||||
HTTP/1.1 200
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"message": "1. Successfully queried the CloudWatch metrics API.\n2. Successfully queried the CloudWatch logs API.",
|
||||
"status": "OK"
|
||||
}
|
||||
```
|
||||
|
||||
## Fetch data source resources by id
|
||||
|
||||
{{< admonition type="warning" >}}
|
||||
This API is deprecated since Grafana v9.0.0 and will be removed in a future release. Refer to the [new data source resources API](#fetch-data-source-resources).
|
||||
{{< /admonition >}}
|
||||
|
||||
`GET /api/datasources/:datasourceId/resources/*`
|
||||
|
||||
Makes a call to the resources endpoint of data source identified by the given `dashboardId`.
|
||||
|
||||
### Examples
|
||||
|
||||
**Example Request**:
|
||||
|
||||
```http
|
||||
GET api/datasources/112/resources/dimension-keys?region=us-east-2&namespace=AWS%2FEC2&dimensionFilters=%7B%7D&metricName=CPUUtilization HTTP/1.1
|
||||
Accept: application/json
|
||||
Content-Type: application/json
|
||||
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
|
||||
```
|
||||
|
||||
**Example Response**:
|
||||
|
||||
```http
|
||||
HTTP/1.1 200
|
||||
Content-Type: application/json
|
||||
|
||||
[
|
||||
{
|
||||
"text": "AutoScalingGroupName",
|
||||
"value": "AutoScalingGroupName",
|
||||
"label": "AutoScalingGroupName"
|
||||
},
|
||||
{
|
||||
"text": "ImageId",
|
||||
"value": "ImageId",
|
||||
"label": "ImageId"
|
||||
},
|
||||
{
|
||||
"text": "InstanceId",
|
||||
"value": "InstanceId",
|
||||
"label": "InstanceId"
|
||||
},
|
||||
{
|
||||
"text": "InstanceType",
|
||||
"value": "InstanceType",
|
||||
"label": "InstanceType"
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
## Fetch data source resources
|
||||
|
||||
`GET /api/datasources/uid/:uid/resources/*`
|
||||
|
||||
Makes a call to the resources endpoint of data source identified by the given `uid`.
|
||||
|
||||
### Examples
|
||||
|
||||
**Example Request**:
|
||||
|
||||
```http
|
||||
GET api/datasources/uid/P8045C56BDA891CB2/resources/dimension-keys?region=us-east-2&namespace=AWS%2FEC2&dimensionFilters=%7B%7D&metricName=CPUUtilization HTTP/1.1
|
||||
Accept: application/json
|
||||
Content-Type: application/json
|
||||
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
|
||||
```
|
||||
|
||||
**Example Response**:
|
||||
|
||||
```http
|
||||
HTTP/1.1 200
|
||||
Content-Type: application/json
|
||||
|
||||
[
|
||||
{
|
||||
"text": "AutoScalingGroupName",
|
||||
"value": "AutoScalingGroupName",
|
||||
"label": "AutoScalingGroupName"
|
||||
},
|
||||
{
|
||||
"text": "ImageId",
|
||||
"value": "ImageId",
|
||||
"label": "ImageId"
|
||||
},
|
||||
{
|
||||
"text": "InstanceId",
|
||||
"value": "InstanceId",
|
||||
"label": "InstanceId"
|
||||
},
|
||||
{
|
||||
"text": "InstanceType",
|
||||
"value": "InstanceType",
|
||||
"label": "InstanceType"
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
## Query a data source
|
||||
|
||||
Queries a data source having a backend implementation.
|
||||
|
||||
`POST /api/ds/query`
|
||||
|
||||
{{< admonition type="note" >}}
|
||||
Grafana's built-in data sources usually have a backend implementation.
|
||||
{{< /admonition >}}
|
||||
|
||||
**Example request for the Test data source**:
|
||||
|
||||
```http
|
||||
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:**
|
||||
|
||||
```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]
|
||||
]
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### Status codes
|
||||
|
||||
| Code | Description |
|
||||
| ---- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| 200 | All data source queries returned a successful response. |
|
||||
| 400 | Bad request due to invalid JSON, missing content type, missing or invalid fields, etc. Or one or more data source queries were unsuccessful. Refer to the body for more details. |
|
||||
| 403 | Access denied. |
|
||||
| 404 | Either the data source or plugin required to fulfil the request could not be found. |
|
||||
| 500 | Unexpected error. Refer to the body and/or server logs for more details. |
|
||||
@@ -0,0 +1,143 @@
|
||||
---
|
||||
aliases:
|
||||
- ../../../http_api/datasource_lbac_rules/ # /docs/grafana/next/http_api/datasource_lbac_rules/
|
||||
- ../../../developers/http_api/datasource_lbac_rules/ # /docs/grafana/next/developers/http_api/datasource_lbac_rules/
|
||||
canonical: https://grafana.com/docs/grafana/latest/developer-resources/api-reference/http-api/datasource_lbac_rules/
|
||||
description: Data Source LBAC rules API
|
||||
keywords:
|
||||
- grafana
|
||||
- http
|
||||
- documentation
|
||||
- api
|
||||
- datasource
|
||||
- lbac
|
||||
- acl
|
||||
- enterprise
|
||||
labels:
|
||||
products:
|
||||
- cloud
|
||||
title: Datasource LBAC rules HTTP API
|
||||
---
|
||||
|
||||
# Data Source LBAC rules API
|
||||
|
||||
LBAC (Label-Based Access Control) rules can be set for teams.
|
||||
|
||||
## Get LBAC rules for a data source
|
||||
|
||||
`GET /api/datasources/uid/:uid/lbac/teams`
|
||||
|
||||
Gets all existing LBAC rules for the data source with the given `uid`.
|
||||
|
||||
**Required permissions**
|
||||
|
||||
| Action | Scope |
|
||||
| ---------------- | ---------------------------------------------------------------------------------------- |
|
||||
| datasources:read | datasources:_<br>datasources:uid:_<br>datasources:uid:my_datasource (single data source) |
|
||||
|
||||
### Examples
|
||||
|
||||
**Example request:**
|
||||
|
||||
```
|
||||
GET /api/datasources/uid/my_datasource/lbac/teams HTTP/1.1
|
||||
Accept: application/json
|
||||
Content-Type: application/json
|
||||
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
|
||||
```
|
||||
|
||||
**Example response:**
|
||||
|
||||
```http
|
||||
HTTP/1.1 200 OK
|
||||
Content-Type: application/json; charset=UTF-8
|
||||
Content-Length: 131
|
||||
|
||||
```
|
||||
|
||||
## Update LBAC rules for a data source
|
||||
|
||||
`PUT /api/datasources/uid/:uid/lbac/teams`
|
||||
|
||||
Updates LBAC rules for teams associated with the data source with the given `uid`. Here you submit a list of teams and the rules for each team.
|
||||
Deleting a team from the list will remove the team's LBAC rules. You have to submit all teams and their rules to be updated, to remove a team's rules, you have to submit the current list of rules without the team.
|
||||
|
||||
**Required permissions**
|
||||
|
||||
| Action | Scope |
|
||||
| ----------------------------- | ---------------------------------------------------------------------------------------- |
|
||||
| datasources:write | datasources:_<br>datasources:uid:_<br>datasources:uid:my_datasource (single data source) |
|
||||
| datasources.permissions:write | datasources:_<br>datasources:uid:_<br>datasources:uid:my_datasource (single data source) |
|
||||
|
||||
### Examples
|
||||
|
||||
**Example request:**
|
||||
|
||||
```http
|
||||
PUT /api/datasources/uid/my_datasource/lbac/teams
|
||||
Accept: application/json
|
||||
Content-Type: application/json
|
||||
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
|
||||
|
||||
{
|
||||
"rules": [
|
||||
{
|
||||
"teamUId": "fdnd1pf4m9sxvc",
|
||||
"rules": [
|
||||
"{ service_name=\"bigquery-sync-mysql\" }"
|
||||
]
|
||||
},
|
||||
{
|
||||
"teamUid": "dfed1p2m9sxvfc",
|
||||
"rules": [
|
||||
"{ service_name=\"api\" }"
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
**Example response:**
|
||||
|
||||
```http
|
||||
HTTP/1.1 200 OK
|
||||
Content-Type: application/json; charset=UTF-8
|
||||
Content-Length: 35
|
||||
|
||||
```
|
||||
"rules": [
|
||||
"{ service_name=\"api\" }"
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
**Example response:**
|
||||
|
||||
```http
|
||||
HTTP/1.1 200 OK
|
||||
Content-Type: application/json; charset=UTF-8
|
||||
Content-Length: 35
|
||||
|
||||
{
|
||||
"id": 1,
|
||||
"message": "Data source LBAC rules updated",
|
||||
"name": "loki",
|
||||
"rules": [
|
||||
{
|
||||
"teamUId": "fdnd1pf4m9sxvc",
|
||||
"rules": [
|
||||
"{ service_name=\"bigquery-sync-mysql\" }"
|
||||
]
|
||||
},
|
||||
{
|
||||
"teamUid": "dfed1p2m9sxvfc",
|
||||
"rules": [
|
||||
"{ service_name=\"api\" }"
|
||||
]
|
||||
}
|
||||
],
|
||||
"uid": "ee1nm1t7spog0e",
|
||||
}
|
||||
```
|
||||
@@ -0,0 +1,344 @@
|
||||
---
|
||||
aliases:
|
||||
- ../../../http_api/datasource_permissions/ # /docs/grafana/next/http_api/datasource_permissions/
|
||||
- ../../../http_api/datasourcepermissions/ # /docs/grafana/next/http_api/datasourcepermissions/
|
||||
- ../../../developers/http_api/datasource_permissions/ # /docs/grafana/next/developers/http_api/datasource_permissions/
|
||||
canonical: https://grafana.com/docs/grafana/latest/developer-resources/api-reference/http-api/datasource_permissions/
|
||||
description: Data Source Permissions API
|
||||
keywords:
|
||||
- grafana
|
||||
- http
|
||||
- documentation
|
||||
- api
|
||||
- datasource
|
||||
- permission
|
||||
- permissions
|
||||
- acl
|
||||
- enterprise
|
||||
labels:
|
||||
products:
|
||||
- enterprise
|
||||
- oss
|
||||
- cloud
|
||||
title: Datasource Permissions HTTP API
|
||||
---
|
||||
|
||||
# Data Source Permissions API
|
||||
|
||||
> The Data Source Permissions is only available in Grafana Enterprise. Read more about [Grafana Enterprise](/docs/grafana/latest/introduction/grafana-enterprise/).
|
||||
|
||||
> If you are running Grafana Enterprise, for some endpoints you'll need to have specific permissions. Refer to [Role-based access control permissions](/docs/grafana/latest/administration/roles-and-permissions/access-control/custom-role-actions-scopes/) for more information.
|
||||
|
||||
This API can be used to list, add and remove permissions for a data source.
|
||||
|
||||
Permissions can be set for a user, team, service account or a basic role (Admin, Editor, Viewer).
|
||||
|
||||
## Get permissions for a data source
|
||||
|
||||
`GET /api/access-control/datasources/:uid`
|
||||
|
||||
Gets all existing permissions for the data source with the given `uid`.
|
||||
|
||||
**Required permissions**
|
||||
|
||||
See note in the [introduction](#data-source-permissions-api) for an explanation.
|
||||
|
||||
| Action | Scope |
|
||||
| ---------------------------- | ------------------------------------------------------------------------------------------ |
|
||||
| datasources.permissions:read | datasources:\*<br>datasources:uid:\*<br>datasources:uid:my_datasource (single data source) |
|
||||
|
||||
### Examples
|
||||
|
||||
**Example request:**
|
||||
|
||||
```http
|
||||
GET /api/access-control/datasources/my_datasource HTTP/1.1
|
||||
Accept: application/json
|
||||
Content-Type: application/json
|
||||
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
|
||||
```
|
||||
|
||||
**Example response:**
|
||||
|
||||
```http
|
||||
HTTP/1.1 200 OK
|
||||
Content-Type: application/json; charset=UTF-8
|
||||
Content-Length: 551
|
||||
|
||||
```
|
||||
|
||||
Status codes:
|
||||
|
||||
- **200** - Ok
|
||||
- **401** - Unauthorized
|
||||
- **403** - Access denied
|
||||
- **500** - Internal error
|
||||
|
||||
## Add or revoke access to a data source for a user
|
||||
|
||||
`POST /api/access-control/datasources/:uid/users/:id`
|
||||
|
||||
Sets user permission for the data source with the given `uid`.
|
||||
|
||||
To add a permission, set the `permission` field to either `Query`, `Edit`, or `Admin`.
|
||||
To remove a permission, set the `permission` field to an empty string.
|
||||
|
||||
**Required permissions**
|
||||
|
||||
See note in the [introduction](#data-source-permissions-api) for an explanation.
|
||||
|
||||
| Action | Scope |
|
||||
| ----------------------------- | ------------------------------------------------------------------------------------------ |
|
||||
| datasources.permissions:write | datasources:\*<br>datasources:uid:\*<br>datasources:uid:my_datasource (single data source) |
|
||||
|
||||
### Examples
|
||||
|
||||
**Example request:**
|
||||
|
||||
```http
|
||||
POST /api/access-control/datasources/my_datasource/users/1
|
||||
Accept: application/json
|
||||
Content-Type: application/json
|
||||
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
|
||||
|
||||
{
|
||||
"permission": "Query",
|
||||
}
|
||||
```
|
||||
|
||||
**Example response:**
|
||||
|
||||
```http
|
||||
HTTP/1.1 200 OK
|
||||
Content-Type: application/json; charset=UTF-8
|
||||
Content-Length: 35
|
||||
|
||||
```
|
||||
|
||||
**Example request:**
|
||||
|
||||
```http
|
||||
POST /api/access-control/datasources/my_datasource/users/1
|
||||
Accept: application/json
|
||||
Content-Type: application/json
|
||||
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
|
||||
|
||||
{
|
||||
"permission": "",
|
||||
}
|
||||
```
|
||||
|
||||
**Example response:**
|
||||
|
||||
```http
|
||||
HTTP/1.1 200 OK
|
||||
Content-Type: application/json; charset=UTF-8
|
||||
Content-Length: 35
|
||||
|
||||
```
|
||||
|
||||
Status codes:
|
||||
|
||||
- **200** - Ok
|
||||
- **400** - Permission cannot be added, see response body for details
|
||||
- **401** - Unauthorized
|
||||
- **403** - Access denied
|
||||
|
||||
## Add or revoke access to a data source for a team
|
||||
|
||||
`POST /api/access-control/datasources/:uid/teams/:id`
|
||||
|
||||
Sets team permission for the data source with the given `uid`.
|
||||
|
||||
To add a permission, set the `permission` field to either `Query`, `Edit`, or `Admin`.
|
||||
To remove a permission, set the `permission` field to an empty string.
|
||||
|
||||
**Required permissions**
|
||||
|
||||
See note in the [introduction](#data-source-permissions-api) for an explanation.
|
||||
|
||||
| Action | Scope |
|
||||
| ----------------------------- | ------------------------------------------------------------------------------------------ |
|
||||
| datasources.permissions:write | datasources:\*<br>datasources:uid:\*<br>datasources:uid:my_datasource (single data source) |
|
||||
|
||||
### Examples
|
||||
|
||||
**Example request:**
|
||||
|
||||
```http
|
||||
POST /api/access-control/datasources/my_datasource/teams/1
|
||||
Accept: application/json
|
||||
Content-Type: application/json
|
||||
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
|
||||
|
||||
{
|
||||
"permission": "Edit",
|
||||
}
|
||||
```
|
||||
|
||||
**Example response:**
|
||||
|
||||
```http
|
||||
HTTP/1.1 200 OK
|
||||
Content-Type: application/json; charset=UTF-8
|
||||
Content-Length: 35
|
||||
|
||||
```
|
||||
|
||||
**Example request:**
|
||||
|
||||
```http
|
||||
POST /api/access-control/datasources/my_datasource/teams/1
|
||||
Accept: application/json
|
||||
Content-Type: application/json
|
||||
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
|
||||
|
||||
{
|
||||
"permission": "",
|
||||
}
|
||||
```
|
||||
|
||||
**Example response:**
|
||||
|
||||
```http
|
||||
HTTP/1.1 200 OK
|
||||
Content-Type: application/json; charset=UTF-8
|
||||
Content-Length: 35
|
||||
|
||||
```
|
||||
|
||||
Status codes:
|
||||
|
||||
- **200** - Ok
|
||||
- **400** - Permission cannot be added, see response body for details
|
||||
- **401** - Unauthorized
|
||||
- **403** - Access denied
|
||||
|
||||
## Add or revoke access to a data source for a basic role
|
||||
|
||||
`POST /api/access-control/datasources/:uid/builtInRoles/:builtinRoleName`
|
||||
|
||||
Sets permission for the data source with the given `uid` to all users who have the specified basic role.
|
||||
|
||||
You can set permissions for the following basic roles: `Admin`, `Editor`, `Viewer`.
|
||||
|
||||
To add a permission, set the `permission` field to either `Query`, `Edit`, or `Admin`.
|
||||
To remove a permission, set the `permission` field to an empty string.
|
||||
|
||||
**Required permissions**
|
||||
|
||||
See note in the [introduction](#data-source-permissions-api) for an explanation.
|
||||
|
||||
| Action | Scope |
|
||||
| ----------------------------- | ------------------------------------------------------------------------------------------ |
|
||||
| datasources.permissions:write | datasources:\*<br>datasources:uid:\*<br>datasources:uid:my_datasource (single data source) |
|
||||
|
||||
### Examples
|
||||
|
||||
**Example request:**
|
||||
|
||||
```http
|
||||
POST /api/access-control/datasources/my_datasource/builtInRoles/Admin
|
||||
Accept: application/json
|
||||
Content-Type: application/json
|
||||
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
|
||||
|
||||
{
|
||||
"permission": "Edit",
|
||||
}
|
||||
```
|
||||
|
||||
**Example response:**
|
||||
|
||||
```http
|
||||
HTTP/1.1 200 OK
|
||||
Content-Type: application/json; charset=UTF-8
|
||||
Content-Length: 35
|
||||
|
||||
```
|
||||
|
||||
**Example request:**
|
||||
|
||||
```http
|
||||
POST /api/access-control/datasources/my_datasource/builtInRoles/Viewer
|
||||
Accept: application/json
|
||||
Content-Type: application/json
|
||||
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
|
||||
|
||||
{
|
||||
"permission": "",
|
||||
}
|
||||
```
|
||||
|
||||
**Example response:**
|
||||
|
||||
```http
|
||||
HTTP/1.1 200 OK
|
||||
Content-Type: application/json; charset=UTF-8
|
||||
Content-Length: 35
|
||||
|
||||
```
|
||||
|
||||
Status codes:
|
||||
|
||||
- **200** - Ok
|
||||
- **400** - Permission cannot be added, see response body for details
|
||||
- **401** - Unauthorized
|
||||
- **403** - Access denied
|
||||
| ----------------------------- | ------------------------------------------------------------------------------------------ |
|
||||
| datasources.permissions:write | datasources:\*<br>datasources:uid:\*<br>datasources:uid:my_datasource (single data source) |
|
||||
|
||||
### Examples
|
||||
|
||||
**Example request:**
|
||||
|
||||
```http
|
||||
POST /api/access-control/datasources/my_datasource/builtInRoles/Admin
|
||||
Accept: application/json
|
||||
Content-Type: application/json
|
||||
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
|
||||
|
||||
{
|
||||
"permission": "Edit",
|
||||
}
|
||||
```
|
||||
|
||||
**Example response:**
|
||||
|
||||
```http
|
||||
HTTP/1.1 200 OK
|
||||
Content-Type: application/json; charset=UTF-8
|
||||
Content-Length: 35
|
||||
|
||||
{"message": "Permission updated"}
|
||||
```
|
||||
|
||||
**Example request:**
|
||||
|
||||
```http
|
||||
POST /api/access-control/datasources/my_datasource/builtInRoles/Viewer
|
||||
Accept: application/json
|
||||
Content-Type: application/json
|
||||
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
|
||||
|
||||
{
|
||||
"permission": "",
|
||||
}
|
||||
```
|
||||
|
||||
**Example response:**
|
||||
|
||||
```http
|
||||
HTTP/1.1 200 OK
|
||||
Content-Type: application/json; charset=UTF-8
|
||||
Content-Length: 35
|
||||
|
||||
{"message": "Permission removed"}
|
||||
```
|
||||
|
||||
Status codes:
|
||||
|
||||
- **200** - Ok
|
||||
- **400** - Permission cannot be added, see response body for details
|
||||
- **401** - Unauthorized
|
||||
- **403** - Access denied
|
||||
@@ -0,0 +1,20 @@
|
||||
---
|
||||
aliases:
|
||||
- ../../../developers/http_api/examples/ # /docs/grafana/next/developers/http_api/examples/
|
||||
canonical: https://grafana.com/docs/grafana/latest/developer-resources/api-reference/http-api/examples/
|
||||
keywords:
|
||||
- grafana
|
||||
- tutorials
|
||||
- API
|
||||
labels:
|
||||
products:
|
||||
- enterprise
|
||||
- oss
|
||||
title: 'HTTP API examples'
|
||||
menuTitle: 'Examples'
|
||||
weight: 02
|
||||
---
|
||||
|
||||
# HTTP API examples
|
||||
|
||||
{{< section >}}
|
||||
@@ -0,0 +1,107 @@
|
||||
---
|
||||
aliases:
|
||||
- ../../../../http_api/create-api-tokens-for-org/ # /docs/grafana/next/http_api/create-api-tokens-for-org/
|
||||
- ../../../../tutorials/api_org_token_howto/ # /docs/grafana/next/tutorials/api_org_token_howto/
|
||||
- ../../../../developers/http_api/examples/create-api-tokens-for-org/ # /docs/grafana/next/developers/http_api/examples/create-api-tokens-for-org/
|
||||
canonical: https://grafana.com/docs/grafana/latest/developer-resources/api-reference/http-api/examples/create-api-tokens-for-org/
|
||||
keywords:
|
||||
- grafana
|
||||
- tutorials
|
||||
- API
|
||||
- Token
|
||||
- Org
|
||||
- Organization
|
||||
labels:
|
||||
products:
|
||||
- enterprise
|
||||
- oss
|
||||
title: 'API Tutorial: Create Service Account tokens and dashboards for an organization'
|
||||
---
|
||||
|
||||
# Create Service Account tokens and dashboards for an organization
|
||||
|
||||
Use the Grafana API to set up new Grafana organizations or to add dynamically generated dashboards to an existing organization.
|
||||
|
||||
## Authentication
|
||||
|
||||
There are two authentication methods to access the API:
|
||||
|
||||
- Basic authentication: A Grafana Admin user can access some parts of the Grafana API through basic authentication.
|
||||
- Service Account tokens: All organization actions can be accessed through a Service Account token. A Service Account token is associated with an organization. It can be used to create dashboards and other components specific for that organization.
|
||||
|
||||
## How to create a new organization and a Service Account Token
|
||||
|
||||
The task is to create a new organization and then add a Token that can be used by other users. In the examples below which use basic auth, the user is `admin` and the password is `admin`.
|
||||
|
||||
1. [Create the org](/docs/grafana/<GRAFANA_VERSION>/http_api/org/#create-organization). Here is an example using curl:
|
||||
|
||||
```bash
|
||||
curl -X POST -H "Content-Type: application/json" -d '{"name":"apiorg"}' http://admin:admin@localhost:3000/api/orgs
|
||||
```
|
||||
|
||||
This should return a response: `{"message":"Organization created","orgId":6}`. Use the orgId for the next steps.
|
||||
|
||||
1. Optional step. If the org was created previously and/or step 3 fails then first [add your Admin user to the org](/docs/grafana/<GRAFANA_VERSION>/http_api/org/#add-user-in-organization):
|
||||
|
||||
```bash
|
||||
curl -X POST -H "Content-Type: application/json" -d '{"loginOrEmail":"admin", "role": "Admin"}' http://admin:admin@localhost:3000/api/orgs/<org id of new org>/users
|
||||
```
|
||||
|
||||
1. [Switch the org context for the Admin user to the new org](/docs/grafana/<GRAFANA_VERSION>/http_api/user/#switch-user-context-for-signed-in-user):
|
||||
|
||||
```bash
|
||||
curl -X POST http://admin:admin@localhost:3000/api/user/using/<id of new org>
|
||||
```
|
||||
|
||||
1. [Create a Service Account](../../serviceaccount/#create-service-account):
|
||||
|
||||
```bash
|
||||
curl -X POST -H "Content-Type: application/json" -d '{"name":"test", "role": "Admin"}' http://admin:admin@localhost:3000/api/serviceaccounts
|
||||
```
|
||||
|
||||
1. [Create a Service Account token](../../serviceaccount/#create-service-account-tokens) for the service account created in the previous step:
|
||||
|
||||
```bash
|
||||
curl -X POST -H "Content-Type: application/json" -d '{"name":"test-token"}' http://admin:admin@localhost:3000/api/serviceaccounts/<service account id>/tokens
|
||||
```
|
||||
|
||||
This should return a response:
|
||||
|
||||
```http
|
||||
HTTP/1.1 200
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"id": 7,
|
||||
"name": "test-token",
|
||||
"key": "eyJrIjoiVjFxTHZ6dGdPSjg5Um92MjN1RlhjMkNqYkZUbm9jYkwiLCJuIjoiZ3JhZmFuYSIsImlkIjoxfQ=="
|
||||
}
|
||||
```
|
||||
|
||||
Save the key returned here in your password manager as it is not possible to fetch again it in the future.
|
||||
|
||||
## How to add a dashboard
|
||||
|
||||
Using the Token that was created in the previous step, you can create a dashboard or carry out other actions without having to switch organizations.
|
||||
|
||||
1. [Add a dashboard](/docs/grafana/<GRAFANA_VERSION>/http_api/dashboard/#create-update-dashboard) using the key (or bearer token as it is also called):
|
||||
|
||||
```bash
|
||||
curl -X POST --insecure -H "Authorization: Bearer eyJrIjoiR0ZXZmt1UFc0OEpIOGN5RWdUalBJTllUTk83VlhtVGwiLCJuIjoiYXBpa2V5Y3VybCIsImlkIjo2fQ==" -H "Content-Type: application/json" -d '{
|
||||
"dashboard": {
|
||||
"id": null,
|
||||
"title": "Production Overview",
|
||||
"tags": [ "templated" ],
|
||||
"timezone": "browser",
|
||||
"rows": [
|
||||
{
|
||||
}
|
||||
],
|
||||
"schemaVersion": 6,
|
||||
"version": 0
|
||||
},
|
||||
"overwrite": false
|
||||
}' http://localhost:3000/api/dashboards/db
|
||||
```
|
||||
|
||||
> **Note:** If you export a dashboard for sharing externally using the Share > Export menu in the Grafana UI, you cannot import that dashboard. Instead, click **View JSON** and save it to a file or fetch the JSON output through the API.
|
||||
@@ -0,0 +1,44 @@
|
||||
---
|
||||
aliases:
|
||||
- ../../../../http_api/curl-examples/ # /docs/grafana/next/http_api/curl-examples/
|
||||
- ../../../../developers/http_api/curl-examples/ # /docs/grafana/next/developers/http_api/curl-examples/
|
||||
- ../../../../developers/http_api/examples/curl-examples/ # /docs/grafana/next/developers/http_api/examples/curl-examples/
|
||||
canonical: https://grafana.com/docs/grafana/latest/developer-resources/api-reference/http-api/examples/curl-examples/
|
||||
description: cURL examples
|
||||
keywords:
|
||||
- grafana
|
||||
- http
|
||||
- documentation
|
||||
- api
|
||||
- curl
|
||||
labels:
|
||||
products:
|
||||
- enterprise
|
||||
- oss
|
||||
title: cURL examples
|
||||
---
|
||||
|
||||
# cURL examples
|
||||
|
||||
This page provides examples of calls to the Grafana API using cURL.
|
||||
|
||||
The most basic example for a dashboard for which there is no authentication. You can test the following on your local machine, assuming a default installation and anonymous access enabled, required:
|
||||
|
||||
```
|
||||
curl http://localhost:3000/api/search
|
||||
```
|
||||
|
||||
Here's a cURL command that works for getting the home dashboard when you are running Grafana locally with [basic authentication](/docs/grafana/<GRAFANA_VERSION>/setup-grafana/configure-access/configure-authentication/#basic-auth) enabled using the default admin credentials:
|
||||
|
||||
```
|
||||
curl http://admin:admin@localhost:3000/api/search
|
||||
```
|
||||
|
||||
To pass a username and password with [HTTP basic authorization](/docs/grafana/<GRAFANA_VERSION>/administration/roles-and-permissions/access-control/manage-rbac-roles/), encode them as base64.
|
||||
You can't use authorization tokens in the request.
|
||||
|
||||
For example, to [list permissions associated with roles](/docs/grafana/<GRAFANA_VERSION>/administration/roles-and-permissions/access-control/manage-rbac-roles/) given a username of `user` and password of `password`, use:
|
||||
|
||||
```
|
||||
curl --location '<grafana_url>/api/access-control/builtin-roles' --user 'user:password'
|
||||
```
|
||||
@@ -0,0 +1,864 @@
|
||||
---
|
||||
aliases:
|
||||
- ../../../http_api/folder/ # /docs/grafana/next/http_api/folder/
|
||||
- ../../../developers/http_api/folder/ # /docs/grafana/next/developers/http_api/folder/
|
||||
canonical: https://grafana.com/docs/grafana/latest/developer-resources/api-reference/http-api/folder/
|
||||
description: Grafana Folder HTTP API
|
||||
keywords:
|
||||
- grafana
|
||||
- http
|
||||
- documentation
|
||||
- api
|
||||
- folder
|
||||
labels:
|
||||
products:
|
||||
- enterprise
|
||||
- oss
|
||||
- cloud
|
||||
title: Folder HTTP API
|
||||
refs:
|
||||
apis:
|
||||
- pattern: /docs/grafana/
|
||||
destination: /docs/grafana/<GRAFANA_VERSION>/developer-resources/api-reference/http-api/apis/
|
||||
- pattern: /docs/grafana-cloud/
|
||||
destination: ./apis/
|
||||
alerting:
|
||||
- pattern: /docs/grafana/
|
||||
destination: /docs/grafana/<GRAFANA_VERSION>/alerting
|
||||
- pattern: /docs/grafana-cloud/
|
||||
destination: /docs/grafana-cloud/alerting-and-irm/alerting/
|
||||
---
|
||||
|
||||
# New Folders APIs
|
||||
|
||||
> If you are running Grafana Enterprise, for some endpoints you'll need to have specific permissions. Refer to [Role-based access control permissions](/docs/grafana/latest/administration/roles-and-permissions/access-control/custom-role-actions-scopes/) for more information.
|
||||
|
||||
> To view more about the new api structure, refer to [API overview](ref:apis).
|
||||
|
||||
### Get all folders
|
||||
|
||||
`GET /apis/folder.grafana.app/v1beta1/namespaces/:namespace/folders`
|
||||
|
||||
Returns all folders that the authenticated user has permission to view within the given organization. Use the `limit` query parameter to control the maximum number of dashboards returned. To retrieve additional dashboards, utilize the `continue` token provided in the response to fetch the next page.
|
||||
|
||||
- namespace: to read more about the namespace to use, see the [API overview](ref:apis).
|
||||
|
||||
**Query parameters**:
|
||||
|
||||
- **`limit`** (optional): Maximum number of folders to return
|
||||
- **`continue`** (optional): Continue token from a previous response to fetch the next page
|
||||
|
||||
**Required permissions**
|
||||
|
||||
See note in the [introduction]({{< ref "#folder-api" >}}) for an explanation.
|
||||
|
||||
| Action | Scope |
|
||||
| -------------- | ----------- |
|
||||
| `folders:read` | `folders:*` |
|
||||
|
||||
**Example Request**:
|
||||
|
||||
```http
|
||||
GET /apis/folder.grafana.app/v1beta1/namespaces/default/folders?limit=1 HTTP/1.1
|
||||
Accept: application/json
|
||||
Content-Type: application/json
|
||||
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
|
||||
```
|
||||
|
||||
**Example Response**:
|
||||
|
||||
```http
|
||||
HTTP/1.1 200
|
||||
Content-Type: application/json
|
||||
{
|
||||
```
|
||||
|
||||
The `metadata.continue` field contains a token to fetch the next page.
|
||||
|
||||
**Example subsequent request using continue token**:
|
||||
|
||||
```http
|
||||
GET /apis/folder.grafana.app/v1beta1/namespaces/default/folders?limit=1&continue=eyJvIjoxNTIsInYiOjE3NjE3MDQyMjQyMDcxODksInMiOmZhbHNlfQ== HTTP/1.1
|
||||
Accept: application/json
|
||||
Content-Type: application/json
|
||||
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
|
||||
```
|
||||
|
||||
**Example subsequent response**:
|
||||
|
||||
```http
|
||||
HTTP/1.1 200
|
||||
Content-Type: application/json
|
||||
{
|
||||
```
|
||||
|
||||
Continue making requests with the updated `continue` token until you receive a response without a `continue` field in the metadata, indicating you've reached the last page.
|
||||
|
||||
Status Codes:
|
||||
|
||||
- **200** – OK
|
||||
- **401** – Unauthorized
|
||||
- **403** – Access Denied
|
||||
|
||||
### Get folder by uid
|
||||
|
||||
`GET /apis/folder.grafana.app/v1beta1/namespaces/:namespace/folders/:uid`
|
||||
|
||||
Will return the folder given the folder uid.
|
||||
|
||||
- namespace: to read more about the namespace to use, see the [API overview](ref:apis).
|
||||
- uid: the unique identifier of the folder to update. this will be the _name_ in the folder response
|
||||
|
||||
**Required permissions**
|
||||
|
||||
See note in the [introduction]({{< ref "#folder-api" >}}) for an explanation.
|
||||
|
||||
| Action | Scope |
|
||||
| -------------- | ----------- |
|
||||
| `folders:read` | `folders:*` |
|
||||
|
||||
**Example Request**:
|
||||
|
||||
```http
|
||||
GET /apis/folder.grafana.app/v1beta1/namespaces/default/folders/aef30vrzxs3y8d HTTP/1.1
|
||||
Accept: application/json
|
||||
Content-Type: application/json
|
||||
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
|
||||
```
|
||||
|
||||
**Example Response**:
|
||||
|
||||
```http
|
||||
HTTP/1.1 200
|
||||
Content-Type: application/json
|
||||
{
|
||||
```
|
||||
|
||||
Note the annotation `grafana.app/folder` which contains the uid of the parent folder.
|
||||
|
||||
Status Codes:
|
||||
|
||||
- **200** – Found
|
||||
- **401** – Unauthorized
|
||||
- **403** – Access Denied
|
||||
- **404** – Folder not found
|
||||
|
||||
### Create folder
|
||||
|
||||
`POST /apis/folder.grafana.app/v1beta1/namespaces/:namespace/folders`
|
||||
|
||||
Creates a new folder.
|
||||
|
||||
- namespace: to read more about the namespace to use, see the [API overview](ref:apis).
|
||||
|
||||
**Required permissions**
|
||||
|
||||
See note in the [introduction]({{< ref "#folder-api" >}}) for an explanation.
|
||||
|
||||
`folders:create` allows creating folders and subfolders. If granted with scope `folders:uid:general`, allows creating root level folders. Otherwise, allows creating subfolders under the specified folders.
|
||||
|
||||
| Action | Scope |
|
||||
| ---------------- | ----------- |
|
||||
| `folders:create` | `folders:*` |
|
||||
| `folders:write` | `folders:*` |
|
||||
|
||||
**Example Request**:
|
||||
|
||||
```http
|
||||
POST /apis/folder.grafana.app/v1beta1/namespaces/default/folders HTTP/1.1
|
||||
Accept: application/json
|
||||
Content-Type: application/json
|
||||
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
|
||||
|
||||
```
|
||||
|
||||
JSON Body schema:
|
||||
|
||||
- **metadata.name** – The Grafana [unique identifier]({{< ref "#identifier-id-vs-unique-identifier-uid" >}}). If you do not want to provide this, set metadata.generateName to the prefix you would like for the uid.
|
||||
- **metadata.annotations.grafana.app/folder** - Optional field, the unique identifier of the parent folder under which the folder should be created. Requires nested folders to be enabled.
|
||||
- **spec.title** – The title of the folder.
|
||||
|
||||
**Example Response**:
|
||||
|
||||
```http
|
||||
HTTP/1.1 200
|
||||
Content-Type: application/json
|
||||
{
|
||||
```
|
||||
|
||||
Status Codes:
|
||||
|
||||
- **201** – Created
|
||||
- **400** – Errors (invalid json, missing or invalid fields, etc)
|
||||
- **401** – Unauthorized
|
||||
- **403** – Access denied
|
||||
- **409** – Conflict (folder with the same uid already exists)
|
||||
|
||||
### Update folder
|
||||
|
||||
`PUT /apis/folder.grafana.app/v1beta1/namespaces/:namespace/folders/:uid`
|
||||
|
||||
Updates an existing folder identified by uid.
|
||||
|
||||
- namespace: to read more about the namespace to use, see the [API overview](ref:apis).
|
||||
- uid: the unique identifier of the folder to update. this will be the _name_ in the folder response
|
||||
|
||||
**Required permissions**
|
||||
|
||||
See note in the [introduction]({{< ref "#folder-api" >}}) for an explanation.
|
||||
|
||||
| Action | Scope |
|
||||
| --------------- | ----------- |
|
||||
| `folders:write` | `folders:*` |
|
||||
|
||||
**Example Request**:
|
||||
|
||||
```http
|
||||
PUT /apis/folder.grafana.app/v1beta1/namespaces/default/folders/fef30w4jaxla8b HTTP/1.1
|
||||
Accept: application/json
|
||||
Content-Type: application/json
|
||||
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
|
||||
|
||||
```
|
||||
|
||||
JSON Body schema:
|
||||
|
||||
- **metadata.name** – The [unique identifier]({{< ref "#identifier-id-vs-unique-identifier-uid" >}}) of the folder.
|
||||
- **metadata.annotations.grafana.app/folder** - Optional field, the unique identifier of the parent folder under which the folder should be - update this to move the folder under a different parent folder. Requires nested folders to be enabled.
|
||||
- **spec.title** – The title of the folder.
|
||||
|
||||
**Example Response**:
|
||||
|
||||
```http
|
||||
HTTP/1.1 200
|
||||
Content-Type: application/json
|
||||
|
||||
```
|
||||
|
||||
Status Codes:
|
||||
|
||||
- **200** – Updated
|
||||
- **400** – Errors (invalid json, missing or invalid fields, etc)
|
||||
- **401** – Unauthorized
|
||||
- **403** – Access Denied
|
||||
- **404** – Folder not found
|
||||
- **412** – Precondition failed (the folder has been changed by someone else). With this status code, the response body will have the following properties:
|
||||
|
||||
```http
|
||||
HTTP/1.1 412 Precondition Failed
|
||||
Content-Type: application/json; charset=UTF-8
|
||||
Content-Length: 97
|
||||
|
||||
```
|
||||
|
||||
### Delete folder
|
||||
|
||||
`DELETE /apis/folder.grafana.app/v1beta1/namespaces/:namespace/folders/:uid`
|
||||
|
||||
Deletes an existing folder identified by UID along with all dashboards (and their alerts) stored in the folder. This operation cannot be reverted.
|
||||
|
||||
If [Grafana Alerting](ref:alerting) is enabled, you can set an optional query parameter `forceDeleteRules=false` so that requests will fail with 400 (Bad Request) error if the folder contains any Grafana alerts. However, if this parameter is set to `true` then it will delete any Grafana alerts under this folder.
|
||||
|
||||
- namespace: to read more about the namespace to use, see the [API overview](ref:apis).
|
||||
- uid: the unique identifier of the folder to delete. this will be the _name_ in the folder response
|
||||
|
||||
**Required permissions**
|
||||
|
||||
See note in the [introduction]({{< ref "#folder-api" >}}) for an explanation.
|
||||
|
||||
| Action | Scope |
|
||||
| ---------------- | ----------- |
|
||||
| `folders:delete` | `folders:*` |
|
||||
|
||||
**Example Request**:
|
||||
|
||||
```http
|
||||
DELETE /apis/folder.grafana.app/v1beta1/namespaces/default/folders/fef30w4jaxla8b HTTP/1.1
|
||||
Accept: application/json
|
||||
Content-Type: application/json
|
||||
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
|
||||
|
||||
```
|
||||
|
||||
**Example Response**:
|
||||
|
||||
```http
|
||||
HTTP/1.1 200
|
||||
Content-Type: application/json
|
||||
|
||||
```
|
||||
|
||||
Status Codes:
|
||||
|
||||
- **200** – Deleted
|
||||
- **401** – Unauthorized
|
||||
- **400** – Bad Request
|
||||
- **403** – Access Denied
|
||||
- **404** – Folder not found
|
||||
|
||||
## APIs
|
||||
|
||||
## Identifier (id) vs unique identifier (uid)
|
||||
|
||||
The unique identifier (uid) of a folder can be used for uniquely identify folders within an org. It's automatically generated if not provided when creating a folder. The uid allows having consistent URLs for accessing folders and when syncing folders between multiple Grafana installs. This means that changing the title of a folder will not break any bookmarked links to that folder.
|
||||
|
||||
The uid can have a maximum length of 40 characters.
|
||||
|
||||
The identifier (id) of a folder is deprecated in favor of the unique identifier (uid).
|
||||
|
||||
### Get all folders
|
||||
|
||||
`GET /api/folders`
|
||||
|
||||
Returns all folders that the authenticated user has permission to view. You can control the maximum number of folders returned through the `limit` query parameter, the default is 1000. You can also pass the `page` query parameter for fetching folders from a page other than the first one.
|
||||
|
||||
If nested folders are enabled, the operation expects an additional optional query parameter `parentUid` with the parent folder UID, and returns the immediate subfolders that the authenticated user has permission to view.
|
||||
If the parameter is not supplied, then the operation returns immediate subfolders under the root
|
||||
that the authenticated user has permission to view.
|
||||
|
||||
**Required permissions**
|
||||
|
||||
See note in the [introduction](#folder-api) for an explanation.
|
||||
|
||||
| Action | Scope |
|
||||
| -------------- | ----------- |
|
||||
| `folders:read` | `folders:*` |
|
||||
|
||||
**Example Request**:
|
||||
|
||||
```http
|
||||
GET /api/folders?limit=10 HTTP/1.1
|
||||
Accept: application/json
|
||||
Content-Type: application/json
|
||||
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
|
||||
```
|
||||
|
||||
**Example Response**:
|
||||
|
||||
```http
|
||||
HTTP/1.1 200
|
||||
Content-Type: application/json
|
||||
|
||||
```
|
||||
|
||||
### Get folder by uid
|
||||
|
||||
`GET /api/folders/:uid`
|
||||
|
||||
Will return the folder given the folder uid.
|
||||
|
||||
**Required permissions**
|
||||
|
||||
See note in the [introduction](#folder-api) for an explanation.
|
||||
|
||||
| Action | Scope |
|
||||
| -------------- | ----------- |
|
||||
| `folders:read` | `folders:*` |
|
||||
|
||||
**Example Request**:
|
||||
|
||||
```http
|
||||
GET /api/folders/nErXDvCkzzh HTTP/1.1
|
||||
Accept: application/json
|
||||
Content-Type: application/json
|
||||
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
|
||||
```
|
||||
|
||||
**Example Response**:
|
||||
|
||||
```http
|
||||
HTTP/1.1 200
|
||||
Content-Type: application/json
|
||||
|
||||
```
|
||||
|
||||
If nested folders are enabled, and the folder is nested (lives under another folder), then the response additionally contains:
|
||||
|
||||
- **parentUid** - The parent folder UID.
|
||||
- **parents** - An array with the whole tree hierarchy, starting from the root going down up to the parent folder.
|
||||
|
||||
Status Codes:
|
||||
|
||||
- **200** – Found
|
||||
- **401** – Unauthorized
|
||||
- **403** – Access Denied
|
||||
- **404** – Folder not found
|
||||
|
||||
### Create folder
|
||||
|
||||
`POST /api/folders`
|
||||
|
||||
Creates a new folder.
|
||||
|
||||
**Required permissions**
|
||||
|
||||
See note in the [introduction](#folder-api) for an explanation.
|
||||
|
||||
`folders:create` allows creating folders and subfolders. If granted with scope `folders:uid:general`, allows creating root level folders. Otherwise, allows creating subfolders under the specified folders.
|
||||
|
||||
| Action | Scope |
|
||||
| ---------------- | ----------- |
|
||||
| `folders:create` | `folders:*` |
|
||||
| `folders:write` | `folders:*` |
|
||||
|
||||
**Example Request**:
|
||||
|
||||
```http
|
||||
POST /api/folders HTTP/1.1
|
||||
Accept: application/json
|
||||
Content-Type: application/json
|
||||
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
|
||||
|
||||
```
|
||||
|
||||
JSON Body schema:
|
||||
|
||||
- **uid** – Optional [unique identifier](#identifier-id-vs-unique-identifier-uid).
|
||||
- **title** – The title of the folder.
|
||||
- **parentUid** - Optional field, the unique identifier of the parent folder under which the folder should be created. Requires nested folders to be enabled.
|
||||
|
||||
**Example Response**:
|
||||
|
||||
```http
|
||||
HTTP/1.1 200
|
||||
Content-Type: application/json
|
||||
|
||||
```
|
||||
|
||||
If nested folders are enabled, and the folder is nested (lives under another folder) then the response additionally contains:
|
||||
|
||||
- **parentUid** - the parent folder UID.
|
||||
- **parents** - an array with the whole tree hierarchy starting from the root going down up to the parent folder.
|
||||
|
||||
Status Codes:
|
||||
|
||||
- **200** – Created
|
||||
- **400** – Errors (invalid json, missing or invalid fields, etc)
|
||||
- **401** – Unauthorized
|
||||
- **403** – Access Denied
|
||||
- **412** - Folder already exists
|
||||
|
||||
### Update folder
|
||||
|
||||
`PUT /api/folders/:uid`
|
||||
|
||||
Updates an existing folder identified by uid.
|
||||
|
||||
**Required permissions**
|
||||
|
||||
See note in the [introduction](#folder-api) for an explanation.
|
||||
|
||||
| Action | Scope |
|
||||
| --------------- | ----------- |
|
||||
| `folders:write` | `folders:*` |
|
||||
|
||||
**Example Request**:
|
||||
|
||||
```http
|
||||
PUT /api/folders/nErXDvCkzz HTTP/1.1
|
||||
Accept: application/json
|
||||
Content-Type: application/json
|
||||
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
|
||||
|
||||
```
|
||||
|
||||
JSON Body schema:
|
||||
|
||||
- **title** – The title of the folder.
|
||||
- **version** – Provide the current version to be able to update the folder. Not needed if `overwrite=true`.
|
||||
- **overwrite** – Set to true if you want to overwrite existing folder with newer version.
|
||||
|
||||
**Example Response**:
|
||||
|
||||
```http
|
||||
HTTP/1.1 200
|
||||
Content-Type: application/json
|
||||
|
||||
```
|
||||
|
||||
If nested folders are enabled, and the folder is nested (lives under another folder) then the response additionally contains:
|
||||
|
||||
- **parentUid** - the parent folder UID.
|
||||
- **parents** - an array with the whole tree hierarchy starting from the root going down up to the parent folder.
|
||||
|
||||
Status Codes:
|
||||
|
||||
- **200** – Updated
|
||||
- **400** – Errors (invalid json, missing or invalid fields, etc)
|
||||
- **401** – Unauthorized
|
||||
- **403** – Access Denied
|
||||
- **404** – Folder not found
|
||||
- **412** – Precondition failed
|
||||
|
||||
The **412** status code is used for explaining that you cannot update the folder and why.
|
||||
There can be different reasons for this:
|
||||
|
||||
- The folder has been changed by someone else, `status=version-mismatch`
|
||||
|
||||
The response body will have the following properties:
|
||||
|
||||
```http
|
||||
HTTP/1.1 412 Precondition Failed
|
||||
Content-Type: application/json; charset=UTF-8
|
||||
Content-Length: 97
|
||||
|
||||
```
|
||||
|
||||
### Delete folder
|
||||
|
||||
`DELETE /api/folders/:uid`
|
||||
|
||||
Deletes an existing folder identified by UID along with all dashboards (and their alerts) stored in the folder. This operation cannot be reverted.
|
||||
|
||||
If [Grafana Alerting](/docs/grafana/latest/alerting/) is enabled, you can set an optional query parameter `forceDeleteRules=false` so that requests will fail with 400 (Bad Request) error if the folder contains any Grafana alerts. However, if this parameter is set to `true` then it will delete any Grafana alerts under this folder.
|
||||
|
||||
**Required permissions**
|
||||
|
||||
See note in the [introduction](#folder-api) for an explanation.
|
||||
|
||||
| Action | Scope |
|
||||
| ---------------- | ----------- |
|
||||
| `folders:delete` | `folders:*` |
|
||||
|
||||
**Example Request**:
|
||||
|
||||
```http
|
||||
DELETE /api/folders/nErXDvCkzz HTTP/1.1
|
||||
Accept: application/json
|
||||
Content-Type: application/json
|
||||
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
|
||||
|
||||
```
|
||||
|
||||
**Example Response**:
|
||||
|
||||
```http
|
||||
HTTP/1.1 200
|
||||
Content-Type: application/json
|
||||
|
||||
```
|
||||
|
||||
Status Codes:
|
||||
|
||||
- **200** – Deleted
|
||||
- **401** – Unauthorized
|
||||
- **400** – Bad Request
|
||||
- **403** – Access Denied
|
||||
- **404** – Folder not found
|
||||
|
||||
### Move folder
|
||||
|
||||
`POST /api/folders/:uid/move`
|
||||
|
||||
Moves the folder.
|
||||
|
||||
This is relevant only if nested folders are enabled.
|
||||
|
||||
**Required permissions**
|
||||
|
||||
See note in the [introduction](#folder-api) for an explanation.
|
||||
|
||||
If moving the folder under another folder:
|
||||
|
||||
| Action | Scope |
|
||||
| ---------------- | ----------------------------------------------------- |
|
||||
| `folders:create` | `folders:uid:<destination folder UID>`<br>`folders:*` |
|
||||
|
||||
If moving the folder under root:
|
||||
| Action | Scope |
|
||||
| -------------- | ------------- |
|
||||
| `folders:create` | `folders:uid:general`<br>`folders:*` |
|
||||
|
||||
JSON body schema:
|
||||
|
||||
- **parentUid** – Optional [unique identifier](#identifier-id-vs-unique-identifier-uid) of the new parent folder. If this is empty, then the folder is moved under the root.
|
||||
|
||||
**Example Request**:
|
||||
|
||||
```http
|
||||
POST /api/folders/a5393ec3-5568-4e88-8809-b866968ae8a6/move HTTP/1.1
|
||||
Accept: application/json
|
||||
Content-Type: application/json
|
||||
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
|
||||
|
||||
```
|
||||
|
||||
**Example Response**:
|
||||
|
||||
```http
|
||||
HTTP/1.1 200
|
||||
Content-Type: application/json
|
||||
|
||||
```
|
||||
|
||||
Status Codes:
|
||||
|
||||
- **200** – Moved
|
||||
- **400** – Errors (invalid JSON, missing or invalid fields, and so on)
|
||||
- **401** – Unauthorized
|
||||
- **403** – Access denied
|
||||
- **404** – Not found
|
||||
|
||||
- **uid** – Optional [unique identifier](#identifier-id-vs-unique-identifier-uid).
|
||||
- **title** – The title of the folder.
|
||||
- **parentUid** - Optional field, the unique identifier of the parent folder under which the folder should be created. Requires nested folders to be enabled.
|
||||
|
||||
**Example Response**:
|
||||
|
||||
```http
|
||||
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
|
||||
}
|
||||
```
|
||||
|
||||
If nested folders are enabled, and the folder is nested (lives under another folder) then the response additionally contains:
|
||||
|
||||
- **parentUid** - the parent folder UID.
|
||||
- **parents** - an array with the whole tree hierarchy starting from the root going down up to the parent folder.
|
||||
|
||||
Status Codes:
|
||||
|
||||
- **200** – Created
|
||||
- **400** – Errors (invalid json, missing or invalid fields, etc)
|
||||
- **401** – Unauthorized
|
||||
- **403** – Access Denied
|
||||
- **412** - Folder already exists
|
||||
|
||||
### Update folder
|
||||
|
||||
`PUT /api/folders/:uid`
|
||||
|
||||
Updates an existing folder identified by uid.
|
||||
|
||||
**Required permissions**
|
||||
|
||||
See note in the [introduction](#folder-api) for an explanation.
|
||||
|
||||
| Action | Scope |
|
||||
| --------------- | ----------- |
|
||||
| `folders:write` | `folders:*` |
|
||||
|
||||
**Example Request**:
|
||||
|
||||
```http
|
||||
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:
|
||||
|
||||
- **title** – The title of the folder.
|
||||
- **version** – Provide the current version to be able to update the folder. Not needed if `overwrite=true`.
|
||||
- **overwrite** – Set to true if you want to overwrite existing folder with newer version.
|
||||
|
||||
**Example Response**:
|
||||
|
||||
```http
|
||||
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
|
||||
}
|
||||
```
|
||||
|
||||
If nested folders are enabled, and the folder is nested (lives under another folder) then the response additionally contains:
|
||||
|
||||
- **parentUid** - the parent folder UID.
|
||||
- **parents** - an array with the whole tree hierarchy starting from the root going down up to the parent folder.
|
||||
|
||||
Status Codes:
|
||||
|
||||
- **200** – Updated
|
||||
- **400** – Errors (invalid json, missing or invalid fields, etc)
|
||||
- **401** – Unauthorized
|
||||
- **403** – Access Denied
|
||||
- **404** – Folder not found
|
||||
- **412** – Precondition failed
|
||||
|
||||
The **412** status code is used for explaining that you cannot update the folder and why.
|
||||
There can be different reasons for this:
|
||||
|
||||
- The folder has been changed by someone else, `status=version-mismatch`
|
||||
|
||||
The response body will have the following properties:
|
||||
|
||||
```http
|
||||
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"
|
||||
}
|
||||
```
|
||||
|
||||
### Delete folder
|
||||
|
||||
`DELETE /api/folders/:uid`
|
||||
|
||||
Deletes an existing folder identified by UID along with all dashboards (and their alerts) stored in the folder. This operation cannot be reverted.
|
||||
|
||||
If [Grafana Alerting](/docs/grafana/latest/alerting/) is enabled, you can set an optional query parameter `forceDeleteRules=false` so that requests will fail with 400 (Bad Request) error if the folder contains any Grafana alerts. However, if this parameter is set to `true` then it will delete any Grafana alerts under this folder.
|
||||
|
||||
**Required permissions**
|
||||
|
||||
See note in the [introduction](#folder-api) for an explanation.
|
||||
|
||||
| Action | Scope |
|
||||
| ---------------- | ----------- |
|
||||
| `folders:delete` | `folders:*` |
|
||||
|
||||
**Example Request**:
|
||||
|
||||
```http
|
||||
DELETE /api/folders/nErXDvCkzz HTTP/1.1
|
||||
Accept: application/json
|
||||
Content-Type: application/json
|
||||
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
|
||||
|
||||
```
|
||||
|
||||
**Example Response**:
|
||||
|
||||
```http
|
||||
HTTP/1.1 200
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"message":"Folder deleted",
|
||||
"id": 2
|
||||
}
|
||||
```
|
||||
|
||||
Status Codes:
|
||||
|
||||
- **200** – Deleted
|
||||
- **401** – Unauthorized
|
||||
- **400** – Bad Request
|
||||
- **403** – Access Denied
|
||||
- **404** – Folder not found
|
||||
|
||||
### Move folder
|
||||
|
||||
`POST /api/folders/:uid/move`
|
||||
|
||||
Moves the folder.
|
||||
|
||||
This is relevant only if nested folders are enabled.
|
||||
|
||||
**Required permissions**
|
||||
|
||||
See note in the [introduction](#folder-api) for an explanation.
|
||||
|
||||
If moving the folder under another folder:
|
||||
|
||||
| Action | Scope |
|
||||
| ---------------- | ----------------------------------------------------- |
|
||||
| `folders:create` | `folders:uid:<destination folder UID>`<br>`folders:*` |
|
||||
|
||||
If moving the folder under root:
|
||||
| Action | Scope |
|
||||
| -------------- | ------------- |
|
||||
| `folders:create` | `folders:uid:general`<br>`folders:*` |
|
||||
|
||||
JSON body schema:
|
||||
|
||||
- **parentUid** – Optional [unique identifier](#identifier-id-vs-unique-identifier-uid) of the new parent folder. If this is empty, then the folder is moved under the root.
|
||||
|
||||
**Example Request**:
|
||||
|
||||
```http
|
||||
POST /api/folders/a5393ec3-5568-4e88-8809-b866968ae8a6/move HTTP/1.1
|
||||
Accept: application/json
|
||||
Content-Type: application/json
|
||||
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
|
||||
|
||||
{
|
||||
"parentUid": "d80b18c0-266a-4aa4-ad5d-5537a00cb8e8",
|
||||
}
|
||||
```
|
||||
|
||||
**Example Response**:
|
||||
|
||||
```http
|
||||
HTTP/1.1 200
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"id": 4,
|
||||
"uid": "a5393ec3-5568-4e88-8809-b866968ae8a6",
|
||||
"title": "just-testing",
|
||||
"url": "/dashboards/f/a5393ec3-5568-4e88-8809-b866968ae8a6/just-testing",
|
||||
"hasAcl": false,
|
||||
"canSave": true,
|
||||
"canEdit": true,
|
||||
"canAdmin": true,
|
||||
"canDelete": true,
|
||||
"createdBy": "Anonymous",
|
||||
"created": "2023-04-27T21:55:01.593741+03:00",
|
||||
"updatedBy": "Anonymous",
|
||||
"updated": "2023-04-27T21:55:15.747444+03:00",
|
||||
"parentUid": "d80b18c0-266a-4aa4-ad5d-5537a00cb8e8",
|
||||
"parents": [
|
||||
{
|
||||
"id": 2,
|
||||
"uid": "d80b18c0-266a-4aa4-ad5d-5537a00cb8e8",
|
||||
"title": "f0",
|
||||
"url": "",
|
||||
"hasAcl": false,
|
||||
"canSave": true,
|
||||
"canEdit": true,
|
||||
"canAdmin": true,
|
||||
"canDelete": true,
|
||||
"createdBy": "Anonymous",
|
||||
"created": "2023-04-27T21:53:46.070672+03:00",
|
||||
"updatedBy": "Anonymous",
|
||||
"updated": "2023-04-27T21:53:46.070673+03:00"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
Status Codes:
|
||||
|
||||
- **200** – Moved
|
||||
- **400** – Errors (invalid JSON, missing or invalid fields, and so on)
|
||||
- **401** – Unauthorized
|
||||
- **403** – Access denied
|
||||
- **404** – Not found
|
||||
@@ -0,0 +1,117 @@
|
||||
---
|
||||
aliases:
|
||||
- ../../../http_api/folder_dashboard_search/ # /docs/grafana/next/http_api/folder_dashboard_search/
|
||||
- ../../../developers/http_api/folder_dashboard_search/ # /docs/grafana/next/developers/http_api/folder_dashboard_search/
|
||||
canonical: https://grafana.com/docs/grafana/latest/developer-resources/api-reference/http-api/folder_dashboard_search/
|
||||
description: Grafana Folder/Dashboard Search HTTP API
|
||||
keywords:
|
||||
- grafana
|
||||
- http
|
||||
- documentation
|
||||
- api
|
||||
- search
|
||||
- folder
|
||||
- dashboard
|
||||
labels:
|
||||
products:
|
||||
- enterprise
|
||||
- oss
|
||||
- cloud
|
||||
title: Folder/Dashboard Search HTTP API
|
||||
---
|
||||
|
||||
# Folder/Dashboard Search API
|
||||
|
||||
## Search folders and dashboards
|
||||
|
||||
`GET /api/search/`
|
||||
|
||||
> Note: When using [Role-based access control](/docs/grafana/latest/administration/roles-and-permissions/access-control/), search results will contain only dashboards and folders which you have access to.
|
||||
|
||||
Query parameters:
|
||||
|
||||
- **query** – Search Query
|
||||
- **tag** – List of tags to search for
|
||||
- **type** – Type to search for, `dash-folder` or `dash-db`
|
||||
- **dashboardIds** – List of dashboard id's to search for
|
||||
- **dashboardUID** - List of dashboard uid's to search for, It is deprecated since Grafana v9.1, please use dashboardUIDs instead
|
||||
- **dashboardUIDs** – List of dashboard uid's to search for
|
||||
- **folderUIDs** – List of folder UIDs to search in
|
||||
- **starred** – Flag indicating if only starred Dashboards should be returned
|
||||
- **limit** – Limit the number of returned results (max is 5000; default is 1000). If an invalid value is provided (for example, strings or special characters), the parameter defaults to 1000.
|
||||
- **page** – Use this parameter to access hits beyond limit. Numbering starts at 1. limit param acts as page size.
|
||||
|
||||
**Example request for retrieving folders and dashboards at the root level**:
|
||||
|
||||
```http
|
||||
GET /api/search?query=&starred=false HTTP/1.1
|
||||
Accept: application/json
|
||||
Content-Type: application/json
|
||||
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
|
||||
```
|
||||
|
||||
**Example response for retrieving folders and dashboards at the root level**:
|
||||
|
||||
```http
|
||||
HTTP/1.1 200
|
||||
Content-Type: application/json
|
||||
|
||||
```
|
||||
|
||||
**Example request searching for dashboards**:
|
||||
|
||||
```http
|
||||
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 searching for dashboards**:
|
||||
|
||||
```http
|
||||
HTTP/1.1 200
|
||||
Content-Type: application/json
|
||||
|
||||
```
|
||||
"type":"dash-db",
|
||||
"tags":[prod],
|
||||
"isStarred":true,
|
||||
"uri":"db/production-overview" // deprecated in Grafana v5.0
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
**Example request searching for dashboards**:
|
||||
|
||||
```http
|
||||
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 searching for dashboards**:
|
||||
|
||||
```http
|
||||
HTTP/1.1 200
|
||||
Content-Type: application/json
|
||||
|
||||
[
|
||||
{
|
||||
"id":1,
|
||||
"uid": "cIBgcSjkk",
|
||||
"orgId": 1,
|
||||
"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
|
||||
}
|
||||
]
|
||||
```
|
||||
@@ -0,0 +1,180 @@
|
||||
---
|
||||
aliases:
|
||||
- ../../../http_api/dashboardpermissions/ # /docs/grafana/next/http_api/dashboardpermissions/
|
||||
- ../../../http_api/folder_permissions/ # /docs/grafana/next/http_api/folder_permissions/
|
||||
- ../../../developers/http_api/folder_permissions/ # /docs/grafana/next/developers/http_api/folder_permissions/
|
||||
canonical: https://grafana.com/docs/grafana/latest/developer-resources/api-reference/http-api/folder_permissions/
|
||||
description: Grafana Folder Permissions HTTP API
|
||||
keywords:
|
||||
- grafana
|
||||
- http
|
||||
- documentation
|
||||
- api
|
||||
- folder
|
||||
- permission
|
||||
- permissions
|
||||
- acl
|
||||
labels:
|
||||
products:
|
||||
- enterprise
|
||||
- oss
|
||||
- cloud
|
||||
title: Folder Permissions HTTP API
|
||||
---
|
||||
|
||||
# Folder Permissions API
|
||||
|
||||
This API can be used to update/get 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:
|
||||
|
||||
- 1 = View
|
||||
- 2 = Edit
|
||||
- 4 = Admin
|
||||
|
||||
> If you are running Grafana Enterprise, for some endpoints you'll need to have specific permissions. Refer to [Role-based access control permissions](/docs/grafana/latest/administration/roles-and-permissions/access-control/custom-role-actions-scopes/) for more information.
|
||||
|
||||
## Get permissions for a folder
|
||||
|
||||
`GET /api/folders/:uid/permissions`
|
||||
|
||||
Gets all existing permissions for the folder with the given `uid`.
|
||||
|
||||
**Required permissions**
|
||||
|
||||
See note in the [introduction](#folder-permission-api) for an explanation.
|
||||
|
||||
| Action | Scope |
|
||||
| -------------------------- | ----------- |
|
||||
| `folders.permissions:read` | `folders:*` |
|
||||
|
||||
**Example request**:
|
||||
|
||||
```http
|
||||
GET /api/folders/nErXDvCkzz/permissions HTTP/1.1
|
||||
Accept: application/json
|
||||
Content-Type: application/json
|
||||
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
|
||||
```
|
||||
|
||||
**Example Response**
|
||||
|
||||
```http
|
||||
HTTP/1.1 200 OK
|
||||
Content-Type: application/json; charset=UTF-8
|
||||
Content-Length: 551
|
||||
|
||||
```
|
||||
|
||||
Status Codes:
|
||||
|
||||
- **200** - Ok
|
||||
- **401** - Unauthorized
|
||||
- **403** - Access denied
|
||||
- **404** - Folder not found
|
||||
|
||||
## Update permissions for a folder
|
||||
|
||||
`POST /api/folders/:uid/permissions`
|
||||
|
||||
Updates permissions for a folder. This operation will remove existing permissions if they're not included in the request.
|
||||
|
||||
**Required permissions**
|
||||
|
||||
See note in the [introduction](#folder-permission-api) for an explanation.
|
||||
|
||||
| Action | Scope |
|
||||
| --------------------------- | ----------- |
|
||||
| `folders.permissions:write` | `folders:*` |
|
||||
|
||||
**Example request**:
|
||||
|
||||
```http
|
||||
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/update. Items that are omitted from the list will be removed.
|
||||
|
||||
**Example response**:
|
||||
|
||||
```http
|
||||
HTTP/1.1 200 OK
|
||||
Content-Type: application/json; charset=UTF-8
|
||||
Content-Length: 35
|
||||
|
||||
```
|
||||
|
||||
Status Codes:
|
||||
|
||||
- **200** - Ok
|
||||
- **401** - Unauthorized
|
||||
- **403** - Access denied
|
||||
- **404** - Dashboard not found
|
||||
"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/update. Items that are omitted from the list will be removed.
|
||||
|
||||
**Example response**:
|
||||
|
||||
```http
|
||||
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** - Ok
|
||||
- **401** - Unauthorized
|
||||
- **403** - Access denied
|
||||
- **404** - Dashboard not found
|
||||
@@ -0,0 +1,478 @@
|
||||
---
|
||||
aliases:
|
||||
- ../../../http_api/library_element/ # /docs/grafana/next/http_api/library_element/
|
||||
- ../../../developers/http_api/library_element/ # /docs/grafana/next/developers/http_api/library_element/
|
||||
canonical: https://grafana.com/docs/grafana/latest/developer-resources/api-reference/http-api/library_element/
|
||||
description: Grafana Library Element HTTP API
|
||||
keywords:
|
||||
- grafana
|
||||
- http
|
||||
- documentation
|
||||
- api
|
||||
- library-element
|
||||
labels:
|
||||
products:
|
||||
- enterprise
|
||||
- oss
|
||||
- cloud
|
||||
title: 'Library Element HTTP API '
|
||||
---
|
||||
|
||||
# Library Element API
|
||||
|
||||
## Identifier (id) vs unique identifier (uid)
|
||||
|
||||
The identifier (ID) of a library element is an auto-incrementing numeric value that is unique per Grafana install.
|
||||
|
||||
The unique identifier (UID) of a library element uniquely identifies library elements between multiple Grafana installs. It's automatically generated unless you specify it during library element creation. The UID provides consistent URLs for accessing library elements and when syncing library elements between multiple Grafana installs.
|
||||
|
||||
The maximum length of a UID is 40 characters.
|
||||
|
||||
## Get all library elements
|
||||
|
||||
`GET /api/library-elements`
|
||||
|
||||
Returns a list of all library elements the authenticated user has permission to view. Use the `perPage` query parameter to control the maximum number of library elements returned; the default limit is 100. You can also use the `page` query parameter to fetch library elements from any page other than the first one.
|
||||
|
||||
Query parameters:
|
||||
|
||||
- `searchString`: Part of the name or description searched for.
|
||||
- `kind`: Kind of element to search for. Use `1` for library panels.
|
||||
- `sortDirection`: Sort order of elements. Use `alpha-asc` for ascending and `alpha-desc` for descending sort order.
|
||||
- `typeFilter`: A comma separated list of types to filter the elements by.
|
||||
- `excludeUid`: Element UID to exclude from search results.
|
||||
- `folderFilter`: A comma separated list of folder IDs to filter the elements by.
|
||||
- `perPage`: The number of results per page; default is 100.
|
||||
- `page`: The page for a set of records, given that only `perPage` records are returned at a time. Numbering starts at `1`.
|
||||
|
||||
**Example Request**:
|
||||
|
||||
```http
|
||||
GET /api/library-elements?perPage=10 HTTP/1.1
|
||||
Accept: application/json
|
||||
Content-Type: application/json
|
||||
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
|
||||
```
|
||||
|
||||
**Example Response**:
|
||||
|
||||
```http
|
||||
HTTP/1.1 200
|
||||
Content-Type: application/json
|
||||
|
||||
```
|
||||
|
||||
Status Codes:
|
||||
|
||||
- `200`: Found
|
||||
- `401`: Unauthorized
|
||||
|
||||
## Get library element by uid
|
||||
|
||||
`GET /api/library-elements/:uid`
|
||||
|
||||
Returns a library element with the given UID.
|
||||
|
||||
**Example Request**:
|
||||
|
||||
```http
|
||||
GET /api/library-elements/V--OrYHnz HTTP/1.1
|
||||
Accept: application/json
|
||||
Content-Type: application/json
|
||||
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
|
||||
```
|
||||
|
||||
**Example Response**:
|
||||
|
||||
```http
|
||||
HTTP/1.1 200
|
||||
Content-Type: application/json
|
||||
|
||||
```
|
||||
|
||||
Status Codes:
|
||||
|
||||
- `200`: Found
|
||||
- `401`: Unauthorized
|
||||
- `404`: Library element not found
|
||||
|
||||
## Get library element by name
|
||||
|
||||
`GET /api/library-elements/name/:name`
|
||||
|
||||
Returns a library element with the given name
|
||||
|
||||
**Example Request**:
|
||||
|
||||
```http
|
||||
GET /api/library-elements/name/API docs Example HTTP/1.1
|
||||
Accept: application/json
|
||||
Content-Type: application/json
|
||||
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
|
||||
```
|
||||
|
||||
**Example Response**:
|
||||
|
||||
```http
|
||||
HTTP/1.1 200
|
||||
Content-Type: application/json
|
||||
|
||||
```
|
||||
|
||||
Status Codes:
|
||||
|
||||
- `200`: Found
|
||||
- `401`: Unauthorized
|
||||
- `404`: Library element not found
|
||||
|
||||
## Get library element connections
|
||||
|
||||
`GET /api/library-elements/:uid/connections`
|
||||
|
||||
Returns a list of connections for a library element based on the UID specified.
|
||||
|
||||
**Example Request**:
|
||||
|
||||
```http
|
||||
GET /api/library-elements/V--OrYHnz/connections HTTP/1.1
|
||||
Accept: application/json
|
||||
Content-Type: application/json
|
||||
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
|
||||
```
|
||||
|
||||
**Example Response**:
|
||||
|
||||
```http
|
||||
HTTP/1.1 200
|
||||
Content-Type: application/json
|
||||
|
||||
```
|
||||
|
||||
Status Codes:
|
||||
|
||||
- `200`: Found
|
||||
- `401`: Unauthorized
|
||||
- `404`: Library element not found
|
||||
|
||||
## Create library element
|
||||
|
||||
`POST /api/library-elements`
|
||||
|
||||
Creates a new library element.
|
||||
|
||||
JSON Body schema:
|
||||
|
||||
- `folderId`: ID of the folder where the library element is stored. It is deprecated since Grafana v9
|
||||
- `folderUid`: Optional, the UID of the folder where the library element is stored, empty string when it is at the root level.
|
||||
- `name`: Optional, the name of the library element.
|
||||
- `model`: The JSON model for the library element.
|
||||
- `kind`: Kind of element to create, Use `1` for library panels.
|
||||
- `uid`: Optional, the [unique identifier](#identifier-id-vs-unique-identifier-uid).
|
||||
|
||||
**Example Request**:
|
||||
|
||||
```http
|
||||
POST /api/library-elements HTTP/1.1
|
||||
Accept: application/json
|
||||
Content-Type: application/json
|
||||
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
|
||||
|
||||
```
|
||||
|
||||
**Example Response**:
|
||||
|
||||
```http
|
||||
HTTP/1.1 200
|
||||
Content-Type: application/json
|
||||
|
||||
```
|
||||
|
||||
Status Codes:
|
||||
|
||||
- `200`: Created
|
||||
- `400`: Errors (for example, name or UID already exists, invalid JSON, missing or invalid fields, and so on).
|
||||
- `401`: Unauthorized
|
||||
- `403`: Access denied
|
||||
|
||||
## Update library element
|
||||
|
||||
`PATCH /api/library-elements/:uid`
|
||||
|
||||
Updates an existing library element identified by uid.
|
||||
|
||||
JSON Body schema:
|
||||
|
||||
- `folderId`: ID of the folder where the library element is stored. It is deprecated since Grafana v9
|
||||
- `folderUid`: UID of the folder where the library element is stored, empty string when it is at the root level.
|
||||
- `name`: Name of the library element.
|
||||
- `model`: The JSON model for the library element.
|
||||
- `kind`: Kind of element to create. Use `1` for library panels.
|
||||
- `version`: Version of the library element you are updating.
|
||||
- `uid`: Optional, the [unique identifier](#identifier-id-vs-unique-identifier-uid).
|
||||
|
||||
**Example Request**:
|
||||
|
||||
```http
|
||||
PATCH /api/library-elements/nErXDvCkzz HTTP/1.1
|
||||
Accept: application/json
|
||||
Content-Type: application/json
|
||||
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
|
||||
|
||||
```
|
||||
|
||||
**Example Response**:
|
||||
|
||||
```http
|
||||
HTTP/1.1 200
|
||||
Content-Type: application/json
|
||||
|
||||
```
|
||||
|
||||
Status Codes:
|
||||
|
||||
- `200`: Updated
|
||||
- `400`: Errors (for example, name or UID already exists, invalid JSON, missing or invalid fields, and so on).
|
||||
- `401`: Unauthorized
|
||||
- `403`: Access denied
|
||||
- `404`: Library element not found
|
||||
- `412`: Version mismatch
|
||||
|
||||
## Delete library element
|
||||
|
||||
`DELETE /api/library-elements/:uid`
|
||||
|
||||
Deletes an existing library element as specified by the UID. This operation cannot be reverted.
|
||||
|
||||
{{< admonition type="note" >}}
|
||||
You cannot delete a library element that is connected. This operation cannot be reverted.
|
||||
{{< /admonition >}}
|
||||
|
||||
**Example Request**:
|
||||
|
||||
```http
|
||||
DELETE /api/library-elements/nErXDvCkzz HTTP/1.1
|
||||
Accept: application/json
|
||||
Content-Type: application/json
|
||||
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
|
||||
|
||||
```
|
||||
|
||||
**Example Response**:
|
||||
|
||||
```http
|
||||
HTTP/1.1 200
|
||||
Content-Type: application/json
|
||||
|
||||
```
|
||||
|
||||
Status Codes:
|
||||
|
||||
- `200`: Deleted
|
||||
- `401`: Unauthorized
|
||||
- `400`: Bad request
|
||||
- `403`: Access denied
|
||||
- `404`: Library element not found
|
||||
- `401`: Unauthorized
|
||||
- `404`: Library element not found
|
||||
|
||||
## Create library element
|
||||
|
||||
`POST /api/library-elements`
|
||||
|
||||
Creates a new library element.
|
||||
|
||||
JSON Body schema:
|
||||
|
||||
- `folderId`: ID of the folder where the library element is stored. It is deprecated since Grafana v9
|
||||
- `folderUid`: Optional, the UID of the folder where the library element is stored, empty string when it is at the root level.
|
||||
- `name`: Optional, the name of the library element.
|
||||
- `model`: The JSON model for the library element.
|
||||
- `kind`: Kind of element to create, Use `1` for library panels.
|
||||
- `uid`: Optional, the [unique identifier](#identifier-id-vs-unique-identifier-uid).
|
||||
|
||||
**Example Request**:
|
||||
|
||||
```http
|
||||
POST /api/library-elements HTTP/1.1
|
||||
Accept: application/json
|
||||
Content-Type: application/json
|
||||
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
|
||||
|
||||
{
|
||||
"uid": "nErXDvCkzz",
|
||||
"folderUid": "",
|
||||
"name": "Example library panel",
|
||||
"model": {...},
|
||||
"kind": 1
|
||||
}
|
||||
```
|
||||
|
||||
**Example Response**:
|
||||
|
||||
```http
|
||||
HTTP/1.1 200
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"result": {
|
||||
"id": 28,
|
||||
"orgId": 1,
|
||||
"folderId": 0,
|
||||
"folderUid": "",
|
||||
"uid": "nErXDvCkzz",
|
||||
"name": "Example library panel",
|
||||
"kind": 1,
|
||||
"type": "",
|
||||
"description": "",
|
||||
"model": {...},
|
||||
"version": 1,
|
||||
"meta": {
|
||||
"folderName": "General",
|
||||
"folderUid": "",
|
||||
"connectedDashboards": 0,
|
||||
"created": "2021-09-30T09:14:22.378307+02:00",
|
||||
"updated": "2021-09-30T09:14:22.378307+02:00",
|
||||
"createdBy": {
|
||||
"id": 1,
|
||||
"name": "admin",
|
||||
"avatarUrl": "/avatar/46d229b033af06a191ff2267bca9ae56"
|
||||
},
|
||||
"updatedBy": {
|
||||
"id": 1,
|
||||
"name": "admin",
|
||||
"avatarUrl": "/avatar/46d229b033af06a191ff2267bca9ae56"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Status Codes:
|
||||
|
||||
- `200`: Created
|
||||
- `400`: Errors (for example, name or UID already exists, invalid JSON, missing or invalid fields, and so on).
|
||||
- `401`: Unauthorized
|
||||
- `403`: Access denied
|
||||
|
||||
## Update library element
|
||||
|
||||
`PATCH /api/library-elements/:uid`
|
||||
|
||||
Updates an existing library element identified by uid.
|
||||
|
||||
JSON Body schema:
|
||||
|
||||
- `folderId`: ID of the folder where the library element is stored. It is deprecated since Grafana v9
|
||||
- `folderUid`: UID of the folder where the library element is stored, empty string when it is at the root level.
|
||||
- `name`: Name of the library element.
|
||||
- `model`: The JSON model for the library element.
|
||||
- `kind`: Kind of element to create. Use `1` for library panels.
|
||||
- `version`: Version of the library element you are updating.
|
||||
- `uid`: Optional, the [unique identifier](#identifier-id-vs-unique-identifier-uid).
|
||||
|
||||
**Example Request**:
|
||||
|
||||
```http
|
||||
PATCH /api/library-elements/nErXDvCkzz HTTP/1.1
|
||||
Accept: application/json
|
||||
Content-Type: application/json
|
||||
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
|
||||
|
||||
{
|
||||
"name": "Renamed library panel",
|
||||
"kind": 1,
|
||||
"version": 1
|
||||
}
|
||||
```
|
||||
|
||||
**Example Response**:
|
||||
|
||||
```http
|
||||
HTTP/1.1 200
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"result": {
|
||||
"id": 28,
|
||||
"orgId": 1,
|
||||
"folderId": 0,
|
||||
"folderUid": "",
|
||||
"uid": "nErXDvCkzz",
|
||||
"name": "Renamed library panel",
|
||||
"kind": 1,
|
||||
"type": "",
|
||||
"description": "",
|
||||
"model": {
|
||||
"description": "",
|
||||
"type": ""
|
||||
},
|
||||
"version": 2,
|
||||
"meta": {
|
||||
"folderName": "General",
|
||||
"folderUid": "",
|
||||
"connectedDashboards": 0,
|
||||
"created": "2021-09-30T09:14:22+02:00",
|
||||
"updated": "2021-09-30T09:25:57.697214+02:00",
|
||||
"createdBy": {
|
||||
"id": 1,
|
||||
"name": "admin",
|
||||
"avatarUrl": "/avatar/46d229b033af06a191ff2267bca9ae56"
|
||||
},
|
||||
"updatedBy": {
|
||||
"id": 1,
|
||||
"name": "admin",
|
||||
"avatarUrl": "/avatar/46d229b033af06a191ff2267bca9ae56"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Status Codes:
|
||||
|
||||
- `200`: Updated
|
||||
- `400`: Errors (for example, name or UID already exists, invalid JSON, missing or invalid fields, and so on).
|
||||
- `401`: Unauthorized
|
||||
- `403`: Access denied
|
||||
- `404`: Library element not found
|
||||
- `412`: Version mismatch
|
||||
|
||||
## Delete library element
|
||||
|
||||
`DELETE /api/library-elements/:uid`
|
||||
|
||||
Deletes an existing library element as specified by the UID. This operation cannot be reverted.
|
||||
|
||||
{{< admonition type="note" >}}
|
||||
You cannot delete a library element that is connected. This operation cannot be reverted.
|
||||
{{< /admonition >}}
|
||||
|
||||
**Example Request**:
|
||||
|
||||
```http
|
||||
DELETE /api/library-elements/nErXDvCkzz HTTP/1.1
|
||||
Accept: application/json
|
||||
Content-Type: application/json
|
||||
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
|
||||
|
||||
```
|
||||
|
||||
**Example Response**:
|
||||
|
||||
```http
|
||||
HTTP/1.1 200
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"message": "Library element deleted",
|
||||
"id": 28
|
||||
}
|
||||
```
|
||||
|
||||
Status Codes:
|
||||
|
||||
- `200`: Deleted
|
||||
- `401`: Unauthorized
|
||||
- `400`: Bad request
|
||||
- `403`: Access denied
|
||||
- `404`: Library element not found
|
||||
@@ -0,0 +1,264 @@
|
||||
---
|
||||
aliases:
|
||||
- ../../../http_api/licensing/ # /docs/grafana/next/http_api/licensing/
|
||||
- ../../../developers/http_api/licensing/ # /docs/grafana/next/developers/http_api/licensing/
|
||||
canonical: https://grafana.com/docs/grafana/latest/developer-resources/api-reference/http-api/licensing/
|
||||
description: Enterprise Licensing HTTP API
|
||||
keywords:
|
||||
- grafana
|
||||
- http
|
||||
- documentation
|
||||
- api
|
||||
- licensing
|
||||
- enterprise
|
||||
labels:
|
||||
products:
|
||||
- enterprise
|
||||
- oss
|
||||
title: Licensing HTTP API
|
||||
---
|
||||
|
||||
# Enterprise License API
|
||||
|
||||
Licensing is only available in Grafana Enterprise. Read more about [Grafana Enterprise](/docs/grafana/latest/introduction/grafana-enterprise/).
|
||||
|
||||
{{< admonition type="caution" >}}
|
||||
You can't authenticate to the Licensing HTTP API with service account tokens.
|
||||
Service accounts are limited to an organization and an organization role.
|
||||
They can't be granted [Grafana server administrator permissions](/docs/grafana/<GRAFANA_VERSION>/administration/roles-and-permissions/#grafana-server-administrators).
|
||||
|
||||
To use these API endpoints you have to use Basic authentication and the Grafana user must have the Grafana server administrator permission.
|
||||
|
||||
The `admin` user that Grafana is provisioned with by default has permissions to use these API endpoints.
|
||||
{{< /admonition >}}
|
||||
|
||||
> If you are running Grafana Enterprise, for some endpoints you'll need to have specific permissions. Refer to [Role-based access control permissions](/docs/grafana/latest/administration/roles-and-permissions/access-control/custom-role-actions-scopes/) for more information.
|
||||
|
||||
## Check license availability
|
||||
|
||||
> **Note:** Available in Grafana Enterprise v7.4+.
|
||||
|
||||
`GET /api/licensing/check`
|
||||
|
||||
Checks if a valid license is available.
|
||||
|
||||
**Required permissions**
|
||||
|
||||
See note in the [introduction](#enterprise-license-api) for an explanation.
|
||||
|
||||
| Action | Scope |
|
||||
| -------------- | ----- |
|
||||
| licensing:read | n/a |
|
||||
|
||||
### Examples
|
||||
|
||||
**Example request:**
|
||||
|
||||
```http
|
||||
GET /api/licensing/check
|
||||
Accept: application/json
|
||||
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
|
||||
```
|
||||
|
||||
**Example response:**
|
||||
|
||||
```http
|
||||
HTTP/1.1 200 OK
|
||||
Content-Type: application/json
|
||||
Content-Length: 4
|
||||
|
||||
```
|
||||
|
||||
Status codes:
|
||||
|
||||
- **200** - OK
|
||||
|
||||
## Add license
|
||||
|
||||
{{< admonition type="note" >}}
|
||||
Available in Grafana Enterprise v7.4+.
|
||||
{{< /admonition >}}
|
||||
|
||||
`POST /api/licensing/token`
|
||||
|
||||
Applies a license to a Grafana instance.
|
||||
|
||||
**Required permissions**
|
||||
|
||||
See note in the [introduction](#enterprise-license-api) for an explanation.
|
||||
|
||||
| Action | Scope |
|
||||
| --------------- | ----- |
|
||||
| licensing:write | n/a |
|
||||
|
||||
### Examples
|
||||
|
||||
**Example request:**
|
||||
|
||||
```http
|
||||
POST /licensing/token
|
||||
Accept: application/json
|
||||
Content-Type: application/json
|
||||
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
|
||||
|
||||
{"token":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ0aGlzIjoiaXMiLCJub3QiOiJhIiwidmFsaWQiOiJsaWNlbnNlIn0.bxDzxIoJlYMwiEYKYT_l2s42z0Y30tY-6KKoyz9RuLE"}
|
||||
```
|
||||
|
||||
**Example response:**
|
||||
|
||||
```http
|
||||
HTTP/1.1 200 OK
|
||||
Content-Type: application/json
|
||||
Content-Length: 357
|
||||
|
||||
```
|
||||
|
||||
The response is a JSON blob with specific values intentionally not shown. The
|
||||
available fields may change at any time without any prior notice. Refer to [Check license availability](#check-license-availability) for information on using the API to check the status of your license.
|
||||
|
||||
Status Codes:
|
||||
|
||||
- **200** - OK
|
||||
- **400** - Bad request
|
||||
- **500** - Internal server error (refer to server logs for more details)
|
||||
|
||||
## Manually force license refresh
|
||||
|
||||
{{< admonition type="note" >}}
|
||||
Available in Grafana Enterprise v7.4+.
|
||||
{{< /admonition >}}
|
||||
|
||||
`POST /api/licensing/token/renew`
|
||||
|
||||
Manually ask license issuer for a new token.
|
||||
|
||||
**Required permissions**
|
||||
|
||||
See note in the [introduction](#enterprise-license-api) for an explanation.
|
||||
|
||||
| Action | Scope |
|
||||
| --------------- | ----- |
|
||||
| licensing:write | n/a |
|
||||
|
||||
### Examples
|
||||
|
||||
**Example request:**
|
||||
|
||||
```http
|
||||
POST /api/licensing/token/renew
|
||||
Accept: application/json
|
||||
Content-Type: application/json
|
||||
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
|
||||
|
||||
{}
|
||||
```
|
||||
|
||||
**Example response:**
|
||||
|
||||
```http
|
||||
HTTP/1.1 200 OK
|
||||
Content-Type: application/json
|
||||
Content-Length: 357
|
||||
|
||||
```
|
||||
|
||||
The response is a JSON blob available for debugging purposes. The
|
||||
available fields may change at any time without any prior notice.
|
||||
|
||||
Status Codes:
|
||||
|
||||
- **200** - OK
|
||||
- **401** - Unauthorized
|
||||
- **403** - Access denied
|
||||
|
||||
## Remove license from database
|
||||
|
||||
{{< admonition type="note" >}}
|
||||
Available in Grafana Enterprise v7.4+.
|
||||
{{< /admonition >}}
|
||||
|
||||
`DELETE /api/licensing/token`
|
||||
|
||||
Removes the license stored in the Grafana database.
|
||||
|
||||
**Required permissions**
|
||||
|
||||
See note in the [introduction](#enterprise-license-api) for an explanation.
|
||||
|
||||
| Action | Scope |
|
||||
| ---------------- | ----- |
|
||||
| licensing:delete | n/a |
|
||||
|
||||
### Examples
|
||||
|
||||
**Example request:**
|
||||
|
||||
```http
|
||||
DELETE /api/licensing/token
|
||||
Accept: application/json
|
||||
Content-Type: application/json
|
||||
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
|
||||
|
||||
{"instance": "http://play.grafana.org/"}
|
||||
```
|
||||
|
||||
JSON Body schema:
|
||||
|
||||
- **instance** – Root URL for the instance for which the license should be deleted. Required.
|
||||
|
||||
**Example response:**
|
||||
|
||||
```http
|
||||
HTTP/1.1 202 Accepted
|
||||
Content-Type: application/json
|
||||
Content-Length: 2
|
||||
|
||||
```
|
||||
|
||||
Status codes:
|
||||
|
||||
- **202** - Accepted, license removed or did not exist.
|
||||
- **401** - Unauthorized
|
||||
- **403** - Access denied
|
||||
- **422** - Unprocessable entity, incorrect instance name provided.
|
||||
**Required permissions**
|
||||
|
||||
See note in the [introduction](#enterprise-license-api) for an explanation.
|
||||
|
||||
| Action | Scope |
|
||||
| ---------------- | ----- |
|
||||
| licensing:delete | n/a |
|
||||
|
||||
### Examples
|
||||
|
||||
**Example request:**
|
||||
|
||||
```http
|
||||
DELETE /api/licensing/token
|
||||
Accept: application/json
|
||||
Content-Type: application/json
|
||||
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
|
||||
|
||||
{"instance": "http://play.grafana.org/"}
|
||||
```
|
||||
|
||||
JSON Body schema:
|
||||
|
||||
- **instance** – Root URL for the instance for which the license should be deleted. Required.
|
||||
|
||||
**Example response:**
|
||||
|
||||
```http
|
||||
HTTP/1.1 202 Accepted
|
||||
Content-Type: application/json
|
||||
Content-Length: 2
|
||||
|
||||
{}
|
||||
```
|
||||
|
||||
Status codes:
|
||||
|
||||
- **202** - Accepted, license removed or did not exist.
|
||||
- **401** - Unauthorized
|
||||
- **403** - Access denied
|
||||
- **422** - Unprocessable entity, incorrect instance name provided.
|
||||
671
docs/sources/developer-resources/api-reference/http-api/org.md
Normal file
671
docs/sources/developer-resources/api-reference/http-api/org.md
Normal file
@@ -0,0 +1,671 @@
|
||||
---
|
||||
aliases:
|
||||
- ../../../http_api/org/ # /docs/grafana/next/http_api/org/
|
||||
- ../../../http_api/organization/ # /docs/grafana/next/http_api/organization/
|
||||
- ../../../developers/http_api/org/ # /docs/grafana/next/developers/http_api/org/
|
||||
canonical: https://grafana.com/docs/grafana/latest/developer-resources/api-reference/http-api/org/
|
||||
description: Grafana Organization HTTP API
|
||||
keywords:
|
||||
- grafana
|
||||
- http
|
||||
- documentation
|
||||
- api
|
||||
- organization
|
||||
labels:
|
||||
products:
|
||||
- enterprise
|
||||
- oss
|
||||
title: Organization HTTP API
|
||||
---
|
||||
|
||||
# Organization API
|
||||
|
||||
The Organization HTTP API is divided in two resources, `/api/org` (current organization)
|
||||
and `/api/orgs` (admin organizations). One big difference between these are that
|
||||
the admin of all organizations API only works with basic authentication, see [Admin Organizations API](#admin-organizations-api) for more information.
|
||||
|
||||
> If you are running Grafana Enterprise, for some endpoints you'll need to have specific permissions. Refer to [Role-based access control permissions](/docs/grafana/latest/administration/roles-and-permissions/access-control/custom-role-actions-scopes/) for more information.
|
||||
|
||||
## Current Organization API
|
||||
|
||||
### Get current Organization
|
||||
|
||||
`GET /api/org/`
|
||||
|
||||
**Required permissions**
|
||||
|
||||
See note in the [introduction](#organization-api) for an explanation.
|
||||
|
||||
| Action | Scope |
|
||||
| --------- | ----- |
|
||||
| orgs:read | N/A |
|
||||
|
||||
**Example Request**:
|
||||
|
||||
```http
|
||||
GET /api/org/ HTTP/1.1
|
||||
Accept: application/json
|
||||
Content-Type: application/json
|
||||
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
|
||||
```
|
||||
|
||||
**Example Response**:
|
||||
|
||||
```http
|
||||
HTTP/1.1 200
|
||||
Content-Type: application/json
|
||||
|
||||
```
|
||||
|
||||
### Get all users within the current organization
|
||||
|
||||
`GET /api/org/users`
|
||||
|
||||
Returns all org users within the current organization.
|
||||
Accessible to users with org admin role.
|
||||
|
||||
**Required permissions**
|
||||
|
||||
See note in the [introduction](#organization-api) for an explanation.
|
||||
|
||||
| Action | Scope |
|
||||
| -------------- | -------- |
|
||||
| org.users:read | users:\* |
|
||||
|
||||
**Example Request**:
|
||||
|
||||
```http
|
||||
GET /api/org/users HTTP/1.1
|
||||
Accept: application/json
|
||||
Content-Type: application/json
|
||||
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
|
||||
```
|
||||
|
||||
**Example Response**:
|
||||
|
||||
```http
|
||||
HTTP/1.1 200
|
||||
Content-Type: application/json
|
||||
|
||||
```
|
||||
|
||||
### Get all users within the current organization (lookup)
|
||||
|
||||
`GET /api/org/users/lookup`
|
||||
|
||||
Returns all org 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.
|
||||
Mainly used by Grafana UI for providing list of users when adding team members and
|
||||
when editing folder/dashboard permissions.
|
||||
|
||||
**Required permissions**
|
||||
|
||||
See note in the [introduction](#organization-api) for an explanation.
|
||||
|
||||
| Action | Scope |
|
||||
| -------------- | -------- |
|
||||
| org.users:read | users:\* |
|
||||
|
||||
**Example Request**:
|
||||
|
||||
```http
|
||||
GET /api/org/users/lookup HTTP/1.1
|
||||
Accept: application/json
|
||||
Content-Type: application/json
|
||||
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
|
||||
```
|
||||
|
||||
**Example Response**:
|
||||
|
||||
```http
|
||||
HTTP/1.1 200
|
||||
Content-Type: application/json
|
||||
|
||||
```
|
||||
|
||||
### Updates the given user
|
||||
|
||||
`PATCH /api/org/users/:userId`
|
||||
|
||||
**Required permissions**
|
||||
|
||||
See note in the [introduction](#organization-api) for an explanation.
|
||||
|
||||
| Action | Scope |
|
||||
| --------------- | -------- |
|
||||
| org.users:write | users:\* |
|
||||
|
||||
**Example Request**:
|
||||
|
||||
```http
|
||||
PATCH /api/org/users/1 HTTP/1.1
|
||||
Accept: application/json
|
||||
Content-Type: application/json
|
||||
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
|
||||
|
||||
```
|
||||
|
||||
**Example Response**:
|
||||
|
||||
```http
|
||||
HTTP/1.1 200
|
||||
Content-Type: application/json
|
||||
|
||||
```
|
||||
|
||||
### Delete user in current organization
|
||||
|
||||
`DELETE /api/org/users/:userId`
|
||||
|
||||
**Required permissions**
|
||||
|
||||
See note in the [introduction](#organization-api) for an explanation.
|
||||
|
||||
| Action | Scope |
|
||||
| ---------------- | -------- |
|
||||
| org.users:remove | users:\* |
|
||||
|
||||
**Example Request**:
|
||||
|
||||
```http
|
||||
DELETE /api/org/users/1 HTTP/1.1
|
||||
Accept: application/json
|
||||
Content-Type: application/json
|
||||
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
|
||||
```
|
||||
|
||||
**Example Response**:
|
||||
|
||||
```http
|
||||
HTTP/1.1 200
|
||||
Content-Type: application/json
|
||||
|
||||
```
|
||||
|
||||
### Update current Organization
|
||||
|
||||
`PUT /api/org`
|
||||
|
||||
**Required permissions**
|
||||
|
||||
See note in the [introduction](#organization-api) for an explanation.
|
||||
|
||||
| Action | Scope |
|
||||
| ---------- | ----- |
|
||||
| orgs:write | N/A |
|
||||
|
||||
**Example Request**:
|
||||
|
||||
```http
|
||||
PUT /api/org HTTP/1.1
|
||||
Accept: application/json
|
||||
Content-Type: application/json
|
||||
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
|
||||
|
||||
```
|
||||
|
||||
**Example Response**:
|
||||
|
||||
```http
|
||||
HTTP/1.1 200
|
||||
Content-Type: application/json
|
||||
|
||||
```
|
||||
|
||||
### Add a new user to the current organization
|
||||
|
||||
`POST /api/org/users`
|
||||
|
||||
Adds a global user to the current organization.
|
||||
|
||||
**Required permissions**
|
||||
|
||||
See note in the [introduction](#organization-api) for an explanation.
|
||||
|
||||
| Action | Scope |
|
||||
| ------------- | -------- |
|
||||
| org.users:add | users:\* |
|
||||
|
||||
**Example Request**:
|
||||
|
||||
```http
|
||||
POST /api/org/users HTTP/1.1
|
||||
Accept: application/json
|
||||
Content-Type: application/json
|
||||
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
|
||||
|
||||
```
|
||||
|
||||
**Example Response**:
|
||||
|
||||
```http
|
||||
HTTP/1.1 200
|
||||
Content-Type: application/json
|
||||
|
||||
```
|
||||
|
||||
## Admin Organizations API
|
||||
|
||||
{{< admonition type="caution" >}}
|
||||
You can't authenticate to the Admin Organizations HTTP API with service account tokens.
|
||||
Service accounts are limited to an organization and an organization role.
|
||||
They can't be granted [Grafana server administrator permissions](/docs/grafana/<GRAFANA_VERSION>/administration/roles-and-permissions/#grafana-server-administrators).
|
||||
|
||||
To use these API endpoints you have to use Basic authentication and the Grafana user must have the Grafana server administrator permission.
|
||||
|
||||
The `admin` user that Grafana is provisioned with by default has permissions to use these API endpoints.
|
||||
{{< /admonition >}}
|
||||
|
||||
### Get Organization by Id
|
||||
|
||||
`GET /api/orgs/:orgId`
|
||||
|
||||
Only works with Basic Authentication (username and password), see [introduction](#admin-organizations-api).
|
||||
|
||||
**Required permissions**
|
||||
|
||||
See note in the [introduction](#organization-api) for an explanation.
|
||||
|
||||
| Action | Scope |
|
||||
| --------- | ----- |
|
||||
| orgs:read | N/A |
|
||||
|
||||
**Example Request**:
|
||||
|
||||
```http
|
||||
GET /api/orgs/1 HTTP/1.1
|
||||
Accept: application/json
|
||||
Content-Type: application/json
|
||||
```
|
||||
|
||||
**Example Response**:
|
||||
|
||||
```http
|
||||
HTTP/1.1 200
|
||||
Content-Type: application/json
|
||||
|
||||
```
|
||||
|
||||
### Get Organization by Name
|
||||
|
||||
`GET /api/orgs/name/:orgName`
|
||||
|
||||
Only works with Basic Authentication (username and password), see [introduction](#admin-organizations-api).
|
||||
|
||||
**Required permissions**
|
||||
|
||||
See note in the [introduction](#organization-api) for an explanation.
|
||||
|
||||
| Action | Scope | Note |
|
||||
| --------- | ----- | ------------------------------ |
|
||||
| orgs:read | N/A | Needs to be assigned globally. |
|
||||
|
||||
**Example Request**:
|
||||
|
||||
```http
|
||||
GET /api/orgs/name/Main%20Org%2E HTTP/1.1
|
||||
Accept: application/json
|
||||
Content-Type: application/json
|
||||
```
|
||||
|
||||
**Example Response**:
|
||||
|
||||
```http
|
||||
HTTP/1.1 200
|
||||
Content-Type: application/json
|
||||
|
||||
```
|
||||
|
||||
### Create Organization
|
||||
|
||||
`POST /api/orgs`
|
||||
|
||||
Only works with Basic Authentication (username and password), see [introduction](#admin-organizations-api).
|
||||
|
||||
**Required permissions**
|
||||
|
||||
See note in the [introduction](#organization-api) for an explanation.
|
||||
|
||||
| Action | Scope | Note |
|
||||
| ----------- | ----- | ------------------------------ |
|
||||
| orgs:create | N/A | Needs to be assigned globally. |
|
||||
|
||||
**Example Request**:
|
||||
|
||||
```http
|
||||
POST /api/orgs HTTP/1.1
|
||||
Accept: application/json
|
||||
Content-Type: application/json
|
||||
|
||||
```
|
||||
|
||||
Note: The api will work in the following two ways
|
||||
|
||||
1. Need to set GF_USERS_ALLOW_ORG_CREATE=true
|
||||
2. Set the config value users.allow_org_create to true in ini file
|
||||
|
||||
**Example Response**:
|
||||
|
||||
```http
|
||||
HTTP/1.1 200
|
||||
Content-Type: application/json
|
||||
|
||||
```
|
||||
|
||||
### Search all Organizations
|
||||
|
||||
`GET /api/orgs?perpage=10&page=1`
|
||||
|
||||
Only works with Basic Authentication (username and password), see [introduction](#admin-organizations-api).
|
||||
|
||||
**Required permissions**
|
||||
|
||||
See note in the [introduction](#organization-api) for an explanation.
|
||||
|
||||
| Action | Scope | Note |
|
||||
| --------- | ----- | ------------------------------ |
|
||||
| orgs:read | N/A | Needs to be assigned globally. |
|
||||
|
||||
**Example Request**:
|
||||
|
||||
```http
|
||||
GET /api/orgs HTTP/1.1
|
||||
Accept: application/json
|
||||
Content-Type: application/json
|
||||
```
|
||||
|
||||
Note: The api will only work when you pass the admin name and password
|
||||
to the request HTTP URL, like http://admin:admin@localhost:3000/api/orgs
|
||||
|
||||
Default value for the `perpage` parameter is `1000` and for the `page` parameter is `0`.
|
||||
|
||||
**Example Response**:
|
||||
|
||||
```http
|
||||
HTTP/1.1 200
|
||||
Content-Type: application/json
|
||||
|
||||
```
|
||||
|
||||
### Update Organization
|
||||
|
||||
`PUT /api/orgs/:orgId`
|
||||
|
||||
Update Organization, fields _Address 1_, _Address 2_, _City_ are not implemented yet.
|
||||
Only works with Basic Authentication (username and password), see [introduction](#admin-organizations-api).
|
||||
|
||||
**Required permissions**
|
||||
|
||||
See note in the [introduction](#organization-api) for an explanation.
|
||||
|
||||
| Action | Scope |
|
||||
| ---------- | ----- |
|
||||
| orgs:write | N/A |
|
||||
|
||||
**Example Request**:
|
||||
|
||||
```http
|
||||
PUT /api/orgs/1 HTTP/1.1
|
||||
Accept: application/json
|
||||
Content-Type: application/json
|
||||
|
||||
```
|
||||
|
||||
**Example Response**:
|
||||
|
||||
```http
|
||||
HTTP/1.1 200
|
||||
Content-Type: application/json
|
||||
|
||||
```
|
||||
|
||||
### Delete Organization
|
||||
|
||||
`DELETE /api/orgs/:orgId`
|
||||
|
||||
Only works with Basic Authentication (username and password), see [introduction](#admin-organizations-api).
|
||||
|
||||
**Required permissions**
|
||||
|
||||
See note in the [introduction](#organization-api) for an explanation.
|
||||
|
||||
| Action | Scope |
|
||||
| ----------- | ----- |
|
||||
| orgs:delete | N/A |
|
||||
|
||||
**Example Request**:
|
||||
|
||||
```http
|
||||
DELETE /api/orgs/1 HTTP/1.1
|
||||
Accept: application/json
|
||||
```
|
||||
|
||||
**Example Response**:
|
||||
|
||||
```http
|
||||
HTTP/1.1 200
|
||||
Content-Type: application/json
|
||||
|
||||
```
|
||||
|
||||
### Get Users in Organization
|
||||
|
||||
`GET /api/orgs/:orgId/users`
|
||||
|
||||
Only works with Basic Authentication (username and password), see [introduction](#admin-organizations-api).
|
||||
|
||||
**Required permissions**
|
||||
|
||||
See note in the [introduction](#organization-api) for an explanation.
|
||||
|
||||
| Action | Scope |
|
||||
| -------------- | -------- |
|
||||
| org.users:read | users:\* |
|
||||
|
||||
**Example Request**:
|
||||
|
||||
```http
|
||||
GET /api/orgs/1/users HTTP/1.1
|
||||
Accept: application/json
|
||||
Content-Type: application/json
|
||||
```
|
||||
|
||||
Note: The api will only work when you pass the admin name and password
|
||||
to the request HTTP URL, like http://admin:admin@localhost:3000/api/orgs/1/users
|
||||
|
||||
**Example Response**:
|
||||
|
||||
```http
|
||||
HTTP/1.1 200
|
||||
Content-Type: application/json
|
||||
[
|
||||
```
|
||||
|
||||
### Add User in Organization
|
||||
|
||||
`POST /api/orgs/:orgId/users`
|
||||
|
||||
Only works with Basic Authentication (username and password), see [introduction](#admin-organizations-api).
|
||||
|
||||
**Required permissions**
|
||||
|
||||
See note in the [introduction](#organization-api) for an explanation.
|
||||
|
||||
| Action | Scope |
|
||||
| ------------- | -------- |
|
||||
| org.users:add | users:\* |
|
||||
|
||||
**Example Request**:
|
||||
|
||||
```http
|
||||
POST /api/orgs/1/users HTTP/1.1
|
||||
Accept: application/json
|
||||
Content-Type: application/json
|
||||
|
||||
```
|
||||
|
||||
**Example Response**:
|
||||
|
||||
```http
|
||||
HTTP/1.1 200
|
||||
Content-Type: application/json
|
||||
|
||||
```
|
||||
|
||||
### Update Users in Organization
|
||||
|
||||
`PATCH /api/orgs/:orgId/users/:userId`
|
||||
|
||||
Only works with Basic Authentication (username and password), see [introduction](#admin-organizations-api).
|
||||
|
||||
**Required permissions**
|
||||
|
||||
See note in the [introduction](#organization-api) for an explanation.
|
||||
|
||||
| Action | Scope |
|
||||
| --------------- | -------- |
|
||||
| org.users:write | users:\* |
|
||||
|
||||
**Example Request**:
|
||||
|
||||
```http
|
||||
PATCH /api/orgs/1/users/2 HTTP/1.1
|
||||
Accept: application/json
|
||||
Content-Type: application/json
|
||||
|
||||
```
|
||||
|
||||
**Example Response**:
|
||||
|
||||
```http
|
||||
HTTP/1.1 200
|
||||
Content-Type: application/json
|
||||
|
||||
```
|
||||
|
||||
### Delete User in Organization
|
||||
|
||||
`DELETE /api/orgs/:orgId/users/:userId`
|
||||
|
||||
Only works with Basic Authentication (username and password), see [introduction](#admin-organizations-api).
|
||||
|
||||
**Required permissions**
|
||||
|
||||
See note in the [introduction](#organization-api) for an explanation.
|
||||
|
||||
| Action | Scope |
|
||||
| ---------------- | -------- |
|
||||
| org.users:remove | users:\* |
|
||||
|
||||
**Example Request**:
|
||||
|
||||
```http
|
||||
DELETE /api/orgs/1/users/2 HTTP/1.1
|
||||
Accept: application/json
|
||||
Content-Type: application/json
|
||||
```
|
||||
|
||||
**Example Response**:
|
||||
|
||||
```http
|
||||
HTTP/1.1 200
|
||||
Content-Type: application/json
|
||||
|
||||
```
|
||||
Only works with Basic Authentication (username and password), see [introduction](#admin-organizations-api).
|
||||
|
||||
**Required permissions**
|
||||
|
||||
See note in the [introduction](#organization-api) for an explanation.
|
||||
|
||||
| Action | Scope |
|
||||
| ------------- | -------- |
|
||||
| org.users:add | users:\* |
|
||||
|
||||
**Example Request**:
|
||||
|
||||
```http
|
||||
POST /api/orgs/1/users HTTP/1.1
|
||||
Accept: application/json
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"loginOrEmail":"user",
|
||||
"role":"Viewer"
|
||||
}
|
||||
```
|
||||
|
||||
**Example Response**:
|
||||
|
||||
```http
|
||||
HTTP/1.1 200
|
||||
Content-Type: application/json
|
||||
|
||||
{"message":"User added to organization", "userId": 1}
|
||||
```
|
||||
|
||||
### Update Users in Organization
|
||||
|
||||
`PATCH /api/orgs/:orgId/users/:userId`
|
||||
|
||||
Only works with Basic Authentication (username and password), see [introduction](#admin-organizations-api).
|
||||
|
||||
**Required permissions**
|
||||
|
||||
See note in the [introduction](#organization-api) for an explanation.
|
||||
|
||||
| Action | Scope |
|
||||
| --------------- | -------- |
|
||||
| org.users:write | users:\* |
|
||||
|
||||
**Example Request**:
|
||||
|
||||
```http
|
||||
PATCH /api/orgs/1/users/2 HTTP/1.1
|
||||
Accept: application/json
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"role":"Admin"
|
||||
}
|
||||
```
|
||||
|
||||
**Example Response**:
|
||||
|
||||
```http
|
||||
HTTP/1.1 200
|
||||
Content-Type: application/json
|
||||
|
||||
{"message":"Organization user updated"}
|
||||
```
|
||||
|
||||
### Delete User in Organization
|
||||
|
||||
`DELETE /api/orgs/:orgId/users/:userId`
|
||||
|
||||
Only works with Basic Authentication (username and password), see [introduction](#admin-organizations-api).
|
||||
|
||||
**Required permissions**
|
||||
|
||||
See note in the [introduction](#organization-api) for an explanation.
|
||||
|
||||
| Action | Scope |
|
||||
| ---------------- | -------- |
|
||||
| org.users:remove | users:\* |
|
||||
|
||||
**Example Request**:
|
||||
|
||||
```http
|
||||
DELETE /api/orgs/1/users/2 HTTP/1.1
|
||||
Accept: application/json
|
||||
Content-Type: application/json
|
||||
```
|
||||
|
||||
**Example Response**:
|
||||
|
||||
```http
|
||||
HTTP/1.1 200
|
||||
Content-Type: application/json
|
||||
|
||||
{"message":"User removed from organization"}
|
||||
```
|
||||
117
docs/sources/developer-resources/api-reference/http-api/other.md
Normal file
117
docs/sources/developer-resources/api-reference/http-api/other.md
Normal file
@@ -0,0 +1,117 @@
|
||||
---
|
||||
aliases:
|
||||
- ../../../http_api/other/ # /docs/grafana/next/http_api/other/
|
||||
- ../../../developers/http_api/other/ # /docs/grafana/next/developers/http_api/other/
|
||||
canonical: https://grafana.com/docs/grafana/latest/developer-resources/api-reference/http-api/other/
|
||||
description: Grafana Other HTTP API
|
||||
keywords:
|
||||
- grafana
|
||||
- http
|
||||
- documentation
|
||||
- api
|
||||
- other
|
||||
labels:
|
||||
products:
|
||||
- enterprise
|
||||
- oss
|
||||
title: 'Other HTTP API '
|
||||
---
|
||||
|
||||
# Frontend Settings API
|
||||
|
||||
## Get Settings
|
||||
|
||||
`GET /api/frontend/settings`
|
||||
|
||||
**Example Request**:
|
||||
|
||||
```http
|
||||
GET /api/frontend/settings HTTP/1.1
|
||||
Accept: application/json
|
||||
Content-Type: application/json
|
||||
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
|
||||
```
|
||||
|
||||
**Example Response**:
|
||||
|
||||
```http
|
||||
HTTP/1.1 200
|
||||
Content-Type: application/json
|
||||
|
||||
```
|
||||
|
||||
# Login API
|
||||
|
||||
## Renew session based on remember cookie
|
||||
|
||||
`GET /api/login/ping`
|
||||
|
||||
**Example Request**:
|
||||
|
||||
```http
|
||||
GET /api/login/ping HTTP/1.1
|
||||
Accept: application/json
|
||||
Content-Type: application/json
|
||||
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
|
||||
```
|
||||
|
||||
**Example Response**:
|
||||
|
||||
```http
|
||||
HTTP/1.1 200
|
||||
Content-Type: application/json
|
||||
|
||||
```
|
||||
|
||||
# Health API
|
||||
|
||||
## Returns health information about Grafana
|
||||
|
||||
`GET /api/health`
|
||||
|
||||
**Example Request**
|
||||
|
||||
```http
|
||||
GET /api/health
|
||||
Accept: application/json
|
||||
```
|
||||
|
||||
**Example Response**:
|
||||
|
||||
```http
|
||||
HTTP/1.1 200 OK
|
||||
|
||||
{
|
||||
"commit": "087143285",
|
||||
"database": "ok",
|
||||
"version": "5.1.3"
|
||||
}
|
||||
```
|
||||
|
||||
{"message": "Logged in"}
|
||||
```
|
||||
|
||||
# Health API
|
||||
|
||||
## Returns health information about Grafana
|
||||
|
||||
`GET /api/health`
|
||||
|
||||
**Example Request**
|
||||
|
||||
```http
|
||||
GET /api/health
|
||||
Accept: application/json
|
||||
```
|
||||
|
||||
**Example Response**:
|
||||
|
||||
```http
|
||||
HTTP/1.1 200 OK
|
||||
|
||||
{
|
||||
"commit": "087143285",
|
||||
"database": "ok",
|
||||
"version": "5.1.3"
|
||||
}
|
||||
```
|
||||
@@ -0,0 +1,261 @@
|
||||
---
|
||||
aliases:
|
||||
- ../../../http_api/playlist/ # /docs/grafana/next/http_api/playlist/
|
||||
- ../../../developers/http_api/playlist/ # /docs/grafana/next/developers/http_api/playlist/
|
||||
canonical: https://grafana.com/docs/grafana/latest/developer-resources/api-reference/http-api/playlist/
|
||||
description: Playlist Admin HTTP API
|
||||
keywords:
|
||||
- grafana
|
||||
- http
|
||||
- documentation
|
||||
- api
|
||||
- playlist
|
||||
labels:
|
||||
products:
|
||||
- enterprise
|
||||
- oss
|
||||
- cloud
|
||||
title: 'Playlist HTTP API '
|
||||
---
|
||||
|
||||
# Playlist API
|
||||
|
||||
## Search Playlist
|
||||
|
||||
`GET /api/playlists`
|
||||
|
||||
Get all existing playlist for the current organization using pagination
|
||||
|
||||
**Example Request**:
|
||||
|
||||
```http
|
||||
GET /api/playlists HTTP/1.1
|
||||
Accept: application/json
|
||||
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
|
||||
```
|
||||
|
||||
Querystring Parameters:
|
||||
|
||||
These parameters are used as querystring parameters.
|
||||
|
||||
- **query** - Limit response to playlist having a name like this value.
|
||||
- **limit** - Limit response to _X_ number of playlist.
|
||||
|
||||
**Example Response**:
|
||||
|
||||
```http
|
||||
HTTP/1.1 200
|
||||
Content-Type: application/json
|
||||
[
|
||||
```
|
||||
|
||||
## Get one playlist
|
||||
|
||||
`GET /api/playlists/:uid`
|
||||
|
||||
**Example Request**:
|
||||
|
||||
```http
|
||||
GET /api/playlists/1 HTTP/1.1
|
||||
Accept: application/json
|
||||
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
|
||||
```
|
||||
|
||||
**Example Response**:
|
||||
|
||||
```http
|
||||
HTTP/1.1 200
|
||||
Content-Type: application/json
|
||||
{
|
||||
```
|
||||
|
||||
## Get Playlist items
|
||||
|
||||
`GET /api/playlists/:uid/items`
|
||||
|
||||
**Example Request**:
|
||||
|
||||
```http
|
||||
GET /api/playlists/1/items HTTP/1.1
|
||||
Accept: application/json
|
||||
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
|
||||
```
|
||||
|
||||
**Example Response**:
|
||||
|
||||
```http
|
||||
HTTP/1.1 200
|
||||
Content-Type: application/json
|
||||
[
|
||||
```
|
||||
|
||||
## Create a playlist
|
||||
|
||||
`POST /api/playlists/`
|
||||
|
||||
**Example Request**:
|
||||
|
||||
```http
|
||||
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_uid",
|
||||
"value": "3",
|
||||
"order": 1,
|
||||
"title":"my third dashboard"
|
||||
},
|
||||
{
|
||||
"type": "dashboard_by_tag",
|
||||
"value": "myTag",
|
||||
"order": 2,
|
||||
"title":"my other dashboard"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
**Example Response**:
|
||||
|
||||
```http
|
||||
HTTP/1.1 200
|
||||
Content-Type: application/json
|
||||
{
|
||||
"uid": "1",
|
||||
"name": "my playlist",
|
||||
"interval": "5m"
|
||||
}
|
||||
```
|
||||
|
||||
## Update a playlist
|
||||
|
||||
`PUT /api/playlists/:uid`
|
||||
|
||||
**Example Request**:
|
||||
|
||||
```http
|
||||
PUT /api/playlists/1 HTTP/1.1
|
||||
Accept: application/json
|
||||
Content-Type: application/json
|
||||
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
|
||||
{
|
||||
"name": "my playlist",
|
||||
"interval": "5m",
|
||||
"items": [
|
||||
{
|
||||
"playlistUid": "1",
|
||||
"type": "dashboard_by_uid",
|
||||
"value": "3",
|
||||
"order": 1,
|
||||
"title":"my third dashboard"
|
||||
},
|
||||
{
|
||||
"playlistUid": "1",
|
||||
"type": "dashboard_by_tag",
|
||||
"value": "myTag",
|
||||
"order": 2,
|
||||
"title":"my other dashboard"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
**Example Response**:
|
||||
|
||||
```http
|
||||
HTTP/1.1 200
|
||||
Content-Type: application/json
|
||||
{
|
||||
```
|
||||
|
||||
## Delete a playlist
|
||||
|
||||
`DELETE /api/playlists/:uid`
|
||||
|
||||
**Example Request**:
|
||||
|
||||
```http
|
||||
DELETE /api/playlists/1 HTTP/1.1
|
||||
Accept: application/json
|
||||
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
|
||||
```
|
||||
|
||||
**Example Response**:
|
||||
|
||||
```http
|
||||
HTTP/1.1 200
|
||||
Content-Type: application/json
|
||||
{}
|
||||
```
|
||||
{
|
||||
"playlistUid": "1",
|
||||
"type": "dashboard_by_uid",
|
||||
"value": "3",
|
||||
"order": 1,
|
||||
"title":"my third dashboard"
|
||||
},
|
||||
{
|
||||
"playlistUid": "1",
|
||||
"type": "dashboard_by_tag",
|
||||
"value": "myTag",
|
||||
"order": 2,
|
||||
"title":"my other dashboard"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
**Example Response**:
|
||||
|
||||
```http
|
||||
HTTP/1.1 200
|
||||
Content-Type: application/json
|
||||
{
|
||||
"uid" : "1",
|
||||
"name": "my playlist",
|
||||
"interval": "5m",
|
||||
"items": [
|
||||
{
|
||||
"id": 1,
|
||||
"playlistUid": "1",
|
||||
"type": "dashboard_by_uid",
|
||||
"value": "3",
|
||||
"order": 1,
|
||||
"title":"my third dashboard"
|
||||
},
|
||||
{
|
||||
"id": 2,
|
||||
"playlistUid": "1",
|
||||
"type": "dashboard_by_tag",
|
||||
"value": "myTag",
|
||||
"order": 2,
|
||||
"title":"my other dashboard"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
## Delete a playlist
|
||||
|
||||
`DELETE /api/playlists/:uid`
|
||||
|
||||
**Example Request**:
|
||||
|
||||
```http
|
||||
DELETE /api/playlists/1 HTTP/1.1
|
||||
Accept: application/json
|
||||
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
|
||||
```
|
||||
|
||||
**Example Response**:
|
||||
|
||||
```http
|
||||
HTTP/1.1 200
|
||||
Content-Type: application/json
|
||||
{}
|
||||
```
|
||||
@@ -0,0 +1,211 @@
|
||||
---
|
||||
aliases:
|
||||
- ../../../http_api/preferences/ # /docs/grafana/next/http_api/preferences/
|
||||
- ../../../developers/http_api/preferences/ # /docs/grafana/next/developers/http_api/preferences/
|
||||
canonical: https://grafana.com/docs/grafana/latest/developer-resources/api-reference/http-api/preferences/
|
||||
description: Grafana HTTP API
|
||||
keywords:
|
||||
- grafana
|
||||
- http
|
||||
- documentation
|
||||
- api
|
||||
- preferences
|
||||
labels:
|
||||
products:
|
||||
- enterprise
|
||||
- oss
|
||||
- cloud
|
||||
title: 'Preferences API'
|
||||
---
|
||||
|
||||
# User and Org Preferences API
|
||||
|
||||
Keys:
|
||||
|
||||
- **theme** - One of: `light`, `dark`, or an empty string for the default theme
|
||||
- **homeDashboardId** - Deprecated. Use `homeDashboardUID` instead.
|
||||
- **homeDashboardUID**: The `:uid` of a dashboard
|
||||
- **timezone** - One of: `utc`, `browser`, or an empty string for the default
|
||||
|
||||
Omitting a key will cause the current value to be replaced with the
|
||||
system default value.
|
||||
|
||||
## Get Current User Prefs
|
||||
|
||||
`GET /api/user/preferences`
|
||||
|
||||
**Example Request**:
|
||||
|
||||
```http
|
||||
GET /api/user/preferences HTTP/1.1
|
||||
Accept: application/json
|
||||
Content-Type: application/json
|
||||
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
|
||||
```
|
||||
|
||||
**Example Response**:
|
||||
|
||||
```http
|
||||
HTTP/1.1 200
|
||||
Content-Type: application/json
|
||||
|
||||
```
|
||||
|
||||
## Update Current User Prefs
|
||||
|
||||
`PUT /api/user/preferences`
|
||||
|
||||
**Example Request**:
|
||||
|
||||
```http
|
||||
PUT /api/user/preferences HTTP/1.1
|
||||
Accept: application/json
|
||||
Content-Type: application/json
|
||||
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
|
||||
|
||||
```
|
||||
|
||||
**Example Response**:
|
||||
|
||||
```http
|
||||
HTTP/1.1 200
|
||||
Content-Type: text/plain; charset=utf-8
|
||||
|
||||
```
|
||||
|
||||
## Patch Current User Prefs
|
||||
|
||||
Update one or more preferences without modifying the others.
|
||||
|
||||
`PATCH /api/user/preferences`
|
||||
|
||||
**Example Request**:
|
||||
|
||||
```http
|
||||
PATCH /api/user/preferences HTTP/1.1
|
||||
Accept: application/json
|
||||
Content-Type: application/json
|
||||
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
|
||||
|
||||
```
|
||||
|
||||
**Example Response**:
|
||||
|
||||
```http
|
||||
HTTP/1.1 200
|
||||
Content-Type: text/plain; charset=utf-8
|
||||
|
||||
```
|
||||
|
||||
## Get Current Org Prefs
|
||||
|
||||
`GET /api/org/preferences`
|
||||
|
||||
**Example Request**:
|
||||
|
||||
```http
|
||||
GET /api/org/preferences HTTP/1.1
|
||||
Accept: application/json
|
||||
Content-Type: application/json
|
||||
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
|
||||
```
|
||||
|
||||
**Example Response**:
|
||||
|
||||
```http
|
||||
HTTP/1.1 200
|
||||
Content-Type: application/json
|
||||
|
||||
```
|
||||
|
||||
## Update Current Org Prefs
|
||||
|
||||
`PUT /api/org/preferences`
|
||||
|
||||
**Example Request**:
|
||||
|
||||
```http
|
||||
PUT /api/org/preferences HTTP/1.1
|
||||
Accept: application/json
|
||||
Content-Type: application/json
|
||||
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
|
||||
|
||||
```
|
||||
|
||||
**Example Response**:
|
||||
|
||||
```http
|
||||
HTTP/1.1 200
|
||||
Content-Type: text/plain; charset=utf-8
|
||||
|
||||
```
|
||||
|
||||
## Patch Current Org Prefs
|
||||
|
||||
Update one or more preferences without modifying the others.
|
||||
|
||||
`PATCH /api/org/preferences`
|
||||
|
||||
**Example Request**:
|
||||
|
||||
```http
|
||||
PATCH /api/org/preferences HTTP/1.1
|
||||
Accept: application/json
|
||||
Content-Type: application/json
|
||||
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
|
||||
|
||||
```
|
||||
|
||||
**Example Response**:
|
||||
|
||||
```http
|
||||
HTTP/1.1 200
|
||||
Content-Type: text/plain; charset=utf-8
|
||||
|
||||
```
|
||||
Content-Type: application/json
|
||||
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
|
||||
|
||||
{
|
||||
"theme": "",
|
||||
"homeDashboardUID":"home",
|
||||
"timezone":"utc"
|
||||
}
|
||||
```
|
||||
|
||||
**Example Response**:
|
||||
|
||||
```http
|
||||
HTTP/1.1 200
|
||||
Content-Type: text/plain; charset=utf-8
|
||||
|
||||
{"message":"Preferences updated"}
|
||||
```
|
||||
|
||||
## Patch Current Org Prefs
|
||||
|
||||
Update one or more preferences without modifying the others.
|
||||
|
||||
`PATCH /api/org/preferences`
|
||||
|
||||
**Example Request**:
|
||||
|
||||
```http
|
||||
PATCH /api/org/preferences HTTP/1.1
|
||||
Accept: application/json
|
||||
Content-Type: application/json
|
||||
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
|
||||
|
||||
{
|
||||
"theme": "dark"
|
||||
}
|
||||
```
|
||||
|
||||
**Example Response**:
|
||||
|
||||
```http
|
||||
HTTP/1.1 200
|
||||
Content-Type: text/plain; charset=utf-8
|
||||
|
||||
{"message":"Preferences updated"}
|
||||
```
|
||||
@@ -0,0 +1,303 @@
|
||||
---
|
||||
aliases:
|
||||
- ../../../http_api/query_caching/ # /docs/grafana/next/http_api/query_caching/
|
||||
- ../../../http_api/resource_caching/ # /docs/grafana/next/http_api/resource_caching/
|
||||
- ../../../http_api/caching/ # /docs/grafana/next/http_api/caching/
|
||||
- ../../../developers/http_api/query_and_resource_caching/ # /docs/grafana/next/developers/http_api/query_and_resource_caching/
|
||||
canonical: https://grafana.com/docs/grafana/latest/developer-resources/api-reference/http-api/query_and_resource_caching/
|
||||
description: Grafana Enterprise Query and Resource Caching HTTP API
|
||||
keywords:
|
||||
- grafana
|
||||
- http
|
||||
- documentation
|
||||
- api
|
||||
- caching
|
||||
- query caching
|
||||
- resource caching
|
||||
- data source
|
||||
labels:
|
||||
products:
|
||||
- enterprise
|
||||
- oss
|
||||
- cloud
|
||||
title: Query and Resource Caching HTTP API
|
||||
---
|
||||
|
||||
# Query and resource caching API
|
||||
|
||||
{{< admonition type="note" >}}
|
||||
If you are running Grafana Enterprise, for some endpoints you'll need to have specific permissions. Refer to [Role-based access control permissions](/docs/grafana/latest/administration/roles-and-permissions/access-control/custom-role-actions-scopes/) for more information.
|
||||
{{< /admonition >}}
|
||||
|
||||
## Enable caching for a data source
|
||||
|
||||
`POST /api/datasources/:dataSourceUID/cache/enable`
|
||||
|
||||
**Required permissions**
|
||||
|
||||
See note in the [introduction](#query-and-resource-caching-api) for an explanation.
|
||||
|
||||
| Action | Scope |
|
||||
| ------------------------- | -------------- |
|
||||
| datasources.caching:write | datasources:\* |
|
||||
|
||||
### Examples
|
||||
|
||||
**Example Request**:
|
||||
|
||||
```http
|
||||
POST /api/datasources/jZrmlLCGka/cache/enable HTTP/1.1
|
||||
Accept: application/json
|
||||
Content-Type: application/json
|
||||
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
|
||||
```
|
||||
|
||||
**Example Response**:
|
||||
|
||||
```http
|
||||
HTTP/1.1 200
|
||||
Content-Type: application/json
|
||||
|
||||
```
|
||||
|
||||
#### Status codes
|
||||
|
||||
| Code | Description |
|
||||
| ---- | ------------------------------------------------------------------------ |
|
||||
| 200 | Cache was successfully enabled for the data source |
|
||||
| 500 | Unexpected error. Refer to the body and/or server logs for more details. |
|
||||
|
||||
## Disable caching for a data source
|
||||
|
||||
`POST /api/datasources/:dataSourceUID/cache/disable`
|
||||
|
||||
**Required permissions**
|
||||
|
||||
See note in the [introduction](#query-and-resource-caching-api) for an explanation.
|
||||
|
||||
| Action | Scope |
|
||||
| ------------------------- | -------------- |
|
||||
| datasources.caching:write | datasources:\* |
|
||||
|
||||
### Examples
|
||||
|
||||
**Example Request**:
|
||||
|
||||
```http
|
||||
POST /api/datasources/jZrmlLCGka/cache/disable HTTP/1.1
|
||||
Accept: application/json
|
||||
Content-Type: application/json
|
||||
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
|
||||
```
|
||||
|
||||
**Example Response**:
|
||||
|
||||
```http
|
||||
HTTP/1.1 200
|
||||
Content-Type: application/json
|
||||
|
||||
```
|
||||
|
||||
#### Status codes
|
||||
|
||||
| Code | Description |
|
||||
| ---- | ------------------------------------------------------------------------ |
|
||||
| 200 | Cache was successfully enabled for the data source |
|
||||
| 500 | Unexpected error. Refer to the body and/or server logs for more details. |
|
||||
|
||||
## Clean cache for all data sources
|
||||
|
||||
`POST /api/datasources/:dataSourceUID/cache/clean`
|
||||
|
||||
Will clean cached data for _all_ data sources with caching enabled. The `dataSourceUID` specified will only be used to return the configuration for that data source.
|
||||
|
||||
**Required permissions**
|
||||
|
||||
See note in the [introduction](#query-and-resource-caching-api) for an explanation.
|
||||
|
||||
| Action | Scope |
|
||||
| ------------------------- | -------------- |
|
||||
| datasources.caching:write | datasources:\* |
|
||||
|
||||
### Examples
|
||||
|
||||
**Example Request**:
|
||||
|
||||
```http
|
||||
POST /api/datasources/jZrmlLCGka/cache/clean HTTP/1.1
|
||||
Accept: application/json
|
||||
Content-Type: application/json
|
||||
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
|
||||
```
|
||||
|
||||
**Example Response**:
|
||||
|
||||
```http
|
||||
HTTP/1.1 200
|
||||
Content-Type: application/json
|
||||
|
||||
```
|
||||
|
||||
#### Status codes
|
||||
|
||||
| Code | Description |
|
||||
| ---- | ------------------------------------------------------------------------ |
|
||||
| 200 | Cache was successfully enabled for the data source |
|
||||
| 500 | Unexpected error. Refer to the body and/or server logs for more details. |
|
||||
|
||||
## Update cache configuration for a data source
|
||||
|
||||
`POST /api/datasources/:dataSourceUID/cache`
|
||||
|
||||
**Required permissions**
|
||||
|
||||
See note in the [introduction](#query-and-resource-caching-api) for an explanation.
|
||||
|
||||
| Action | Scope |
|
||||
| ------------------------- | -------------- |
|
||||
| datasources.caching:write | datasources:\* |
|
||||
|
||||
### Examples
|
||||
|
||||
**Example Request**:
|
||||
|
||||
```http
|
||||
POST /api/datasources/jZrmlLCGka/cache HTTP/1.1
|
||||
Accept: application/json
|
||||
Content-Type: application/json
|
||||
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
|
||||
|
||||
```
|
||||
|
||||
#### JSON Body Schema
|
||||
|
||||
| Field name | Data type | Description |
|
||||
| -------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| dataSourceID | number | The ID of the data source to configure. |
|
||||
| dataSourceUID | string | The UID of the data source to configure. |
|
||||
| enabled | boolean | Whether or not to enable caching for this data source. |
|
||||
| useDefaultTTL | boolean | Whether the configured default TTL (Time-To-Live) should be used for both query and resource caching, instead of the user-specified values. |
|
||||
| ttlQueriesMs | number | The TTL to use for query caching, in milliseconds. |
|
||||
| ttlResourcesMs | number | The TTL to use for resource caching, in milliseconds. |
|
||||
|
||||
**Example Response**:
|
||||
|
||||
```http
|
||||
HTTP/1.1 200
|
||||
Content-Type: application/json
|
||||
|
||||
```
|
||||
|
||||
#### Status codes
|
||||
|
||||
| Code | Description |
|
||||
| ---- | ------------------------------------------------------------------------ |
|
||||
| 200 | Cache was successfully enabled for the data source |
|
||||
| 400 | Request errors (invalid json, missing or invalid fields, etc) |
|
||||
| 500 | Unexpected error. Refer to the body and/or server logs for more details. |
|
||||
|
||||
## Get cache configuration for a data source
|
||||
|
||||
`GET /api/datasources/:dataSourceUID/cache`
|
||||
|
||||
**Required permissions**
|
||||
|
||||
See note in the [introduction](#query-and-resource-caching-api) for an explanation.
|
||||
|
||||
| Action | Scope |
|
||||
| ------------------------ | -------------- |
|
||||
| datasources.caching:read | datasources:\* |
|
||||
|
||||
### Examples
|
||||
|
||||
**Example Request**:
|
||||
|
||||
```http
|
||||
GET /api/datasources/jZrmlLCGka/cache HTTP/1.1
|
||||
Accept: application/json
|
||||
Content-Type: application/json
|
||||
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
|
||||
```
|
||||
|
||||
**Example Response**:
|
||||
|
||||
```http
|
||||
HTTP/1.1 200
|
||||
Content-Type: application/json
|
||||
|
||||
```
|
||||
|
||||
#### Status codes
|
||||
|
||||
| Code | Description |
|
||||
| ---- | ------------------------------------------------------------------------ |
|
||||
| 200 | Cache was successfully enabled for the data source |
|
||||
| 500 | Unexpected error. Refer to the body and/or server logs for more details. |
|
||||
"dataSourceUID": "jZrmlLCGka",
|
||||
"enabled": true,
|
||||
"useDefaultTTL": false,
|
||||
"ttlQueriesMs": 60000,
|
||||
"ttlResourcesMs": 300000,
|
||||
"defaultTTLMs": 300000,
|
||||
"created": "2023-04-21T11:49:22-04:00",
|
||||
"updated": "2023-04-24T17:03:40-04:00"
|
||||
}
|
||||
```
|
||||
|
||||
#### Status codes
|
||||
|
||||
| Code | Description |
|
||||
| ---- | ------------------------------------------------------------------------ |
|
||||
| 200 | Cache was successfully enabled for the data source |
|
||||
| 400 | Request errors (invalid json, missing or invalid fields, etc) |
|
||||
| 500 | Unexpected error. Refer to the body and/or server logs for more details. |
|
||||
|
||||
## Get cache configuration for a data source
|
||||
|
||||
`GET /api/datasources/:dataSourceUID/cache`
|
||||
|
||||
**Required permissions**
|
||||
|
||||
See note in the [introduction](#query-and-resource-caching-api) for an explanation.
|
||||
|
||||
| Action | Scope |
|
||||
| ------------------------ | -------------- |
|
||||
| datasources.caching:read | datasources:\* |
|
||||
|
||||
### Examples
|
||||
|
||||
**Example Request**:
|
||||
|
||||
```http
|
||||
GET /api/datasources/jZrmlLCGka/cache HTTP/1.1
|
||||
Accept: application/json
|
||||
Content-Type: application/json
|
||||
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
|
||||
```
|
||||
|
||||
**Example Response**:
|
||||
|
||||
```http
|
||||
HTTP/1.1 200
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"message": "Data source cache settings loaded",
|
||||
"dataSourceID": 1,
|
||||
"dataSourceUID": "jZrmlLCGka",
|
||||
"enabled": true,
|
||||
"useDefaultTTL": false,
|
||||
"ttlQueriesMs": 60000,
|
||||
"ttlResourcesMs": 300000,
|
||||
"defaultTTLMs": 300000,
|
||||
"created": "2023-04-21T11:49:22-04:00",
|
||||
"updated": "2023-04-24T17:03:40-04:00"
|
||||
}
|
||||
```
|
||||
|
||||
#### Status codes
|
||||
|
||||
| Code | Description |
|
||||
| ---- | ------------------------------------------------------------------------ |
|
||||
| 200 | Cache was successfully enabled for the data source |
|
||||
| 500 | Unexpected error. Refer to the body and/or server logs for more details. |
|
||||
@@ -0,0 +1,343 @@
|
||||
---
|
||||
aliases:
|
||||
- ../../../http_api/query_history/ # /docs/grafana/next/http_api/query_history/
|
||||
- ../../../developers/http_api/query_history/ # /docs/grafana/next/developers/http_api/query_history/
|
||||
canonical: https://grafana.com/docs/grafana/latest/developer-resources/api-reference/http-api/query_history/
|
||||
description: Grafana Query History HTTP API
|
||||
keywords:
|
||||
- grafana
|
||||
- http
|
||||
- documentation
|
||||
- api
|
||||
- queryHistory
|
||||
labels:
|
||||
products:
|
||||
- enterprise
|
||||
- oss
|
||||
- cloud
|
||||
title: 'Query History HTTP API '
|
||||
---
|
||||
|
||||
# Query history API
|
||||
|
||||
This API can be used to add queries to Query history. It requires that the user is logged in and that Query history feature is enabled in config file.
|
||||
|
||||
## Add query to Query history
|
||||
|
||||
`POST /api/query-history`
|
||||
|
||||
Adds query to query history.
|
||||
|
||||
**Example request:**
|
||||
|
||||
```http
|
||||
POST /api/query-history HTTP/1.1
|
||||
Accept: application/json
|
||||
Content-Type: application/json
|
||||
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
|
||||
{
|
||||
```
|
||||
|
||||
JSON body schema:
|
||||
|
||||
- **datasourceUid** – Data source uid.
|
||||
- **queries** – JSON of query or queries.
|
||||
|
||||
**Example response:**
|
||||
|
||||
```http
|
||||
HTTP/1.1 200
|
||||
Content-Type: application/json
|
||||
{
|
||||
```
|
||||
|
||||
Status codes:
|
||||
|
||||
- **200** – OK
|
||||
- **400** - Errors (invalid JSON, missing or invalid fields)
|
||||
- **401** – Unauthorized
|
||||
- **500** – Internal error
|
||||
|
||||
## Query history search
|
||||
|
||||
`GET /api/query-history`
|
||||
|
||||
Returns a list of queries in the query history that matches the search criteria. Query history search supports pagination. Use the `limit` parameter to control the maximum number of queries returned; the default limit is 100. You can also use the `page` query parameter to fetch queries from any page other than the first one.
|
||||
|
||||
Query parameters:
|
||||
|
||||
- **datasourceUid** - Filter the query history for the selected data source. To perform an "AND" filtering with multiple data sources, specify the data source parameter using the following format: `datasourceUid=uid1&datasourceUid=uid2`.
|
||||
- **searchString** – Filter the query history based on the content.
|
||||
- **sort** - Specify the sorting order. Sorting can be `time-asc` or `time-desc`. The default is `time-desc`.
|
||||
- **onlyStarred** - Search for queries that are starred. Defaults to `false`.
|
||||
- **page** - Search supports pagination. Specify which page number to return. Use the limit parameter to specify the number of queries per page.
|
||||
- **limit** - Limits the number of returned query history items per page. The default is 100 queries per page.
|
||||
- **from/to** - Specifies time range for the query history search. The time can be either epoch timestamps in milliseconds or relative using Grafana time units. For example, now-5m.
|
||||
|
||||
**Example request for query history search**:
|
||||
|
||||
```http
|
||||
GET /api/query-history?datasourceUid="PE1C5CBDA0504A6A3"&datasourceUid="FG1C1CBDA0504A6EL"&searchString="ALERTS"&sort="time-asc" HTTP/1.1
|
||||
Accept: application/json
|
||||
Content-Type: application/json
|
||||
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
|
||||
```
|
||||
|
||||
**Example response for query history search**:
|
||||
|
||||
```http
|
||||
HTTP/1.1 200
|
||||
Content-Type: application/json
|
||||
{
|
||||
```
|
||||
|
||||
Status codes:
|
||||
|
||||
- **200** – OK
|
||||
- **401** – Unauthorized
|
||||
- **500** – Internal error
|
||||
|
||||
## Delete query from Query history by UID
|
||||
|
||||
`DELETE /api/query-history/:uid`
|
||||
|
||||
Deletes the query in query history that matches the specified uid. It requires that the user is logged in and that Query history feature is enabled in config file.
|
||||
|
||||
**Example Request**:
|
||||
|
||||
```http
|
||||
DELETE /api/query-history/P8zM2I1nz HTTP/1.1
|
||||
Accept: application/json
|
||||
Content-Type: application/json
|
||||
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
|
||||
```
|
||||
|
||||
**Example Response**:
|
||||
|
||||
```http
|
||||
HTTP/1.1 200
|
||||
Content-Type: application/json
|
||||
|
||||
```
|
||||
|
||||
Status codes:
|
||||
|
||||
- **200** – OK
|
||||
- **401** – Unauthorized
|
||||
- **500** – Internal error
|
||||
|
||||
## Update comment of query in Query history by UID
|
||||
|
||||
`PATCH /api/query-history/:uid`
|
||||
|
||||
Updates comment of a query with a specific uid that is stored in the query history.
|
||||
|
||||
Query parameters:
|
||||
|
||||
- **comment** – New comment that will be added to the specified query.
|
||||
|
||||
**Example Request**:
|
||||
|
||||
```http
|
||||
PATCH /api/query-history/P8zM2I1nz HTTP/1.1
|
||||
Accept: application/json
|
||||
Content-Type: application/json
|
||||
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
|
||||
{
|
||||
```
|
||||
|
||||
**Example Response**:
|
||||
|
||||
```http
|
||||
HTTP/1.1 200
|
||||
Content-Type: application/json
|
||||
{
|
||||
```
|
||||
|
||||
Status codes:
|
||||
|
||||
- **200** – OK
|
||||
- **400** - Errors (invalid JSON, missing or invalid fields)
|
||||
- **401** – Unauthorized
|
||||
- **500** – Internal error
|
||||
|
||||
## Star query in Query history
|
||||
|
||||
`POST /api/query-history/star/:uid`
|
||||
|
||||
Stars query in query history.
|
||||
|
||||
**Example request:**
|
||||
|
||||
```http
|
||||
POST /api/query-history/star/P8zM2I1nz HTTP/1.1
|
||||
Accept: application/json
|
||||
Content-Type: application/json
|
||||
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
|
||||
```
|
||||
|
||||
**Example response:**
|
||||
|
||||
```http
|
||||
HTTP/1.1 200
|
||||
Content-Type: application/json
|
||||
{
|
||||
```
|
||||
|
||||
Status codes:
|
||||
|
||||
- **200** – OK
|
||||
- **401** – Unauthorized
|
||||
- **500** – Internal error
|
||||
|
||||
## Unstar query in Query history
|
||||
|
||||
`DELETE /api/query-history/star/:uid`
|
||||
|
||||
Removes stars from query in query history.
|
||||
|
||||
**Example request:**
|
||||
|
||||
```http
|
||||
DELETE /api/query-history/star/P8zM2I1nz HTTP/1.1
|
||||
Accept: application/json
|
||||
Content-Type: application/json
|
||||
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
|
||||
```
|
||||
|
||||
**Example response:**
|
||||
|
||||
```http
|
||||
HTTP/1.1 200
|
||||
Content-Type: application/json
|
||||
{
|
||||
```
|
||||
|
||||
Status codes:
|
||||
|
||||
- **200** – OK
|
||||
- **401** – Unauthorized
|
||||
- **500** – Internal error
|
||||
"createdBy": 1,
|
||||
"createdAt": 1643630762,
|
||||
"starred": false,
|
||||
"comment": "Debugging query",
|
||||
"queries": [
|
||||
{
|
||||
"refId": "A",
|
||||
"key": "Q-87fed8e3-62ba-4eb2-8d2a-4129979bb4de-0",
|
||||
"scenarioId": "csv_content",
|
||||
"datasource": {
|
||||
"type": "testdata",
|
||||
"uid": "PD8C576611E62080A"
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Status codes:
|
||||
|
||||
- **200** – OK
|
||||
- **400** - Errors (invalid JSON, missing or invalid fields)
|
||||
- **401** – Unauthorized
|
||||
- **500** – Internal error
|
||||
|
||||
## Star query in Query history
|
||||
|
||||
`POST /api/query-history/star/:uid`
|
||||
|
||||
Stars query in query history.
|
||||
|
||||
**Example request:**
|
||||
|
||||
```http
|
||||
POST /api/query-history/star/P8zM2I1nz HTTP/1.1
|
||||
Accept: application/json
|
||||
Content-Type: application/json
|
||||
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
|
||||
```
|
||||
|
||||
**Example response:**
|
||||
|
||||
```http
|
||||
HTTP/1.1 200
|
||||
Content-Type: application/json
|
||||
{
|
||||
"result": {
|
||||
"uid": "P8zM2I1nz",
|
||||
"datasourceUid": "PE1C5CBDA0504A6A3",
|
||||
"createdBy": 1,
|
||||
"createdAt": 1643630762,
|
||||
"starred": false,
|
||||
"comment": "Debugging query",
|
||||
"queries": [
|
||||
{
|
||||
"refId": "A",
|
||||
"key": "Q-87fed8e3-62ba-4eb2-8d2a-4129979bb4de-0",
|
||||
"scenarioId": "csv_content",
|
||||
"datasource": {
|
||||
"type": "testdata",
|
||||
"uid": "PD8C576611E62080A"
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Status codes:
|
||||
|
||||
- **200** – OK
|
||||
- **401** – Unauthorized
|
||||
- **500** – Internal error
|
||||
|
||||
## Unstar query in Query history
|
||||
|
||||
`DELETE /api/query-history/star/:uid`
|
||||
|
||||
Removes stars from query in query history.
|
||||
|
||||
**Example request:**
|
||||
|
||||
```http
|
||||
DELETE /api/query-history/star/P8zM2I1nz HTTP/1.1
|
||||
Accept: application/json
|
||||
Content-Type: application/json
|
||||
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
|
||||
```
|
||||
|
||||
**Example response:**
|
||||
|
||||
```http
|
||||
HTTP/1.1 200
|
||||
Content-Type: application/json
|
||||
{
|
||||
"result": {
|
||||
"uid": "P8zM2I1nz",
|
||||
"datasourceUid": "PE1C5CBDA0504A6A3",
|
||||
"createdBy": 1,
|
||||
"createdAt": 1643630762,
|
||||
"starred": false,
|
||||
"comment": "Debugging query",
|
||||
"queries": [
|
||||
{
|
||||
"refId": "A",
|
||||
"key": "Q-87fed8e3-62ba-4eb2-8d2a-4129979bb4de-0",
|
||||
"scenarioId": "csv_content",
|
||||
"datasource": {
|
||||
"type": "testdata",
|
||||
"uid": "PD8C576611E62080A"
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Status codes:
|
||||
|
||||
- **200** – OK
|
||||
- **401** – Unauthorized
|
||||
- **500** – Internal error
|
||||
@@ -0,0 +1,681 @@
|
||||
---
|
||||
aliases:
|
||||
- ../../../http_api/reporting/ # /docs/grafana/next/http_api/reporting/
|
||||
- ../../../developers/http_api/reporting/ # /docs/grafana/next/developers/http_api/reporting/
|
||||
canonical: https://grafana.com/docs/grafana/latest/developer-resources/api-reference/http-api/reporting/
|
||||
description: Grafana Enterprise APIs
|
||||
keywords:
|
||||
- grafana
|
||||
- enterprise
|
||||
- api
|
||||
- reporting
|
||||
labels:
|
||||
products:
|
||||
- enterprise
|
||||
- oss
|
||||
- cloud
|
||||
title: Reporting API
|
||||
---
|
||||
|
||||
# Reporting API
|
||||
|
||||
This API allows you to interact programmatically with the [Reporting](/docs/grafana/latest/dashboards/create-reports/) feature.
|
||||
|
||||
> The Reporting API is not stabilized yet, it is still in active development and may change without prior notice.
|
||||
|
||||
> Reporting is only available in Grafana Enterprise. Read more about [Grafana Enterprise](/docs/grafana/latest/introduction/grafana-enterprise/).
|
||||
|
||||
> If you are running Grafana Enterprise, for some endpoints you'll need to have specific permissions. Refer to [Role-based access control permissions](/docs/grafana/latest/administration/roles-and-permissions/access-control/custom-role-actions-scopes/) for more information.
|
||||
|
||||
## List all reports
|
||||
|
||||
`GET /api/reports`
|
||||
|
||||
#### Required permissions
|
||||
|
||||
See note in the [introduction](#reporting-api) for an explanation.
|
||||
|
||||
| Action | Scope |
|
||||
| ------------ | --------------------------- |
|
||||
| reports:read | reports:\*<br>reports:id:\* |
|
||||
|
||||
### Example request
|
||||
|
||||
```http
|
||||
GET /api/reports HTTP/1.1
|
||||
Accept: application/json
|
||||
Content-Type: application/json
|
||||
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
|
||||
```
|
||||
|
||||
### Example response
|
||||
|
||||
```http
|
||||
HTTP/1.1 200 OK
|
||||
Content-Type: application/json
|
||||
Content-Length: 1840
|
||||
|
||||
```
|
||||
|
||||
### Status Codes
|
||||
|
||||
- **200** – OK
|
||||
- **401** - Authentication failed, refer to [Authentication API](/docs/grafana/latest/developers/http_api/auth/).
|
||||
- **500** – Unexpected error or server misconfiguration. Refer to server logs for more details.
|
||||
|
||||
## Get a report
|
||||
|
||||
`GET /api/reports/:id`
|
||||
|
||||
#### Required permissions
|
||||
|
||||
See note in the [introduction](#reporting-api) for an explanation.
|
||||
|
||||
| Action | Scope |
|
||||
| ------------ | ---------------------------------------------------------- |
|
||||
| reports:read | reports:\*<br>reports:id:\*<br>reports:id:1(single report) |
|
||||
|
||||
### Example request
|
||||
|
||||
```http
|
||||
GET /api/reports/2 HTTP/1.1
|
||||
Accept: application/json
|
||||
Content-Type: application/json
|
||||
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
|
||||
```
|
||||
|
||||
### Example response
|
||||
|
||||
```http
|
||||
HTTP/1.1 200 OK
|
||||
Content-Type: application/json
|
||||
Content-Length: 940
|
||||
|
||||
```
|
||||
|
||||
### Status Codes
|
||||
|
||||
- **200** – OK
|
||||
- **400** – Bad request (invalid report ID).
|
||||
- **401** - Authentication failed, refer to [Authentication API](/docs/grafana/latest/developers/http_api/auth/).
|
||||
- **403** – Forbidden (access denied to a report or a dashboard used in the report).
|
||||
- **404** – Not found (such report does not exist).
|
||||
- **500** – Unexpected error or server misconfiguration. Refer to server logs for more details.
|
||||
|
||||
## Create a report
|
||||
|
||||
`POST /api/reports`
|
||||
|
||||
#### Required permissions
|
||||
|
||||
See note in the [introduction](#reporting-api) for an explanation.
|
||||
|
||||
| Action | Scope |
|
||||
| -------------- | ----- |
|
||||
| reports:create | n/a |
|
||||
|
||||
### Example request
|
||||
|
||||
```http
|
||||
POST /api/reports HTTP/1.1
|
||||
Accept: application/json
|
||||
Content-Type: application/json
|
||||
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
|
||||
|
||||
```
|
||||
|
||||
#### Config JSON Body Schema
|
||||
|
||||
| Field name | Data type | Description |
|
||||
| ------------------ | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| name | string | Name of the report that is used as an email subject. |
|
||||
| recipients | string | Comma-separated list of emails to which to send the report to. |
|
||||
| replyTo | string | Comma-separated list of emails used in a reply-to field of the report email. |
|
||||
| message | string | Text message used for the body of the report email. |
|
||||
| startDate | string | Report distribution starts from this date. |
|
||||
| endDate | string | Report distribution ends on this date. |
|
||||
| frequency | string | Specifies how often the report should be sent. Can be `once`, `hourly`, `daily`, `weekly`, `monthly`, `last` or `custom`.<br/><br/>`last` - schedules the report for the last day of month.<br/><br/>`custom` - schedules the report to be sent on a custom interval.<br/>It requires `intervalFrequency` and `intervalAmount` to be specified: for example, every 2 weeks, where 2 is an `intervalAmount` and `weeks` is an `intervalFrequency`. |
|
||||
| intervalFrequency | string | The type of the `custom` interval: `hours`, `days`, `weeks`, `months`. |
|
||||
| intervalAmount | number | `custom` interval amount. |
|
||||
| workdaysOnly | string | Send the report only on Monday-Friday. Applicable to `hourly` and `daily` types of schedule. |
|
||||
| timeZone | string | Time zone used to schedule report execution. |
|
||||
| orientation | string | Can be `portrait` or `landscape`. |
|
||||
| layout | string | Can be `grid` or `simple`. |
|
||||
| enableDashboardUrl | bool | Adds a dashboard url to the bottom of the report email. |
|
||||
| formats | []string | Specified what kind of attachment to generate for the report - `csv`, `pdf`, `image`.<br/>`pdf` is the default one.<br/>`csv` attaches a CSV file for each table panel.<br/>`image` embeds an image of a dashboard into the email's body. |
|
||||
| dashboards | []object | Dashboards to generate a report for.<br/> See "Report Dashboard Schema" section below. |
|
||||
|
||||
#### Report Dashboard Schema
|
||||
|
||||
| Field name | Data type | Description |
|
||||
| ------------------------------ | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| dashboard.uid | string | Dashboard [UID](../dashboard#identifier-id-vs-unique-identifier-uid). |
|
||||
| timeRange.from | string | Dashboard time range from. |
|
||||
| timeRange.to | string | Dashboard time range to. |
|
||||
| reportVariables.<variableName> | string | Key-value pairs containing the template variables for this report, in JSON format. If empty, the template variables from the report's dashboard will be used. |
|
||||
|
||||
### Example response
|
||||
|
||||
```http
|
||||
HTTP/1.1 200 OK
|
||||
Content-Type: application/json
|
||||
Content-Length: 35
|
||||
|
||||
```
|
||||
|
||||
### Status Codes
|
||||
|
||||
- **200** – OK
|
||||
- **400** – Bad request (invalid json, missing or invalid fields values, etc.).
|
||||
- **403** - Forbidden (access denied to a report or a dashboard used in the report).
|
||||
- **500** - Unexpected error or server misconfiguration. Refer to server logs for more details
|
||||
|
||||
## Update a report
|
||||
|
||||
`PUT /api/reports/:id`
|
||||
|
||||
#### Required permissions
|
||||
|
||||
See note in the [introduction](#reporting-api) for an explanation.
|
||||
|
||||
| Action | Scope |
|
||||
| ------------- | --------------------------------------------------------- |
|
||||
| reports:write | reports:\*</br>reports:id:\*</br>reports:1(single report) |
|
||||
|
||||
### Example request
|
||||
|
||||
See [JSON body schema](#config-json-body-schema) for fields description.
|
||||
|
||||
```http
|
||||
GET /api/reports HTTP/1.1
|
||||
Accept: application/json
|
||||
Content-Type: application/json
|
||||
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
|
||||
|
||||
```
|
||||
|
||||
### Example response
|
||||
|
||||
```http
|
||||
HTTP/1.1 200 OK
|
||||
Content-Type: application/json
|
||||
Content-Length: 28
|
||||
|
||||
```
|
||||
|
||||
### Status Codes
|
||||
|
||||
- **200** – OK
|
||||
- **400** – Bad request (invalid json, missing or invalid fields values, etc.).
|
||||
- **401** - Authentication failed, refer to [Authentication API](/docs/grafana/latest/developers/http_api/auth/).
|
||||
- **403** – Forbidden (access denied to a report or a dashboard used in the report).
|
||||
- **404** – Not found (such report does not exist).
|
||||
- **500** – Unexpected error or server misconfiguration. Refer to server logs for more details.
|
||||
|
||||
## Delete a report
|
||||
|
||||
`DELETE /api/reports/:id`
|
||||
|
||||
#### Required permissions
|
||||
|
||||
See note in the [introduction](#reporting-api) for an explanation.
|
||||
|
||||
| Action | Scope |
|
||||
| -------------- | --------------------------------------------------------- |
|
||||
| reports:delete | reports:\*</br>reports:id:\*</br>reports:1(single report) |
|
||||
|
||||
### Example request
|
||||
|
||||
```http
|
||||
DELETE /api/reports/6 HTTP/1.1
|
||||
Accept: application/json
|
||||
Content-Type: application/json
|
||||
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
|
||||
```
|
||||
|
||||
### Example response
|
||||
|
||||
```http
|
||||
HTTP/1.1 200 OK
|
||||
Content-Type: application/json
|
||||
Content-Length: 39
|
||||
|
||||
```
|
||||
|
||||
### Status Codes
|
||||
|
||||
- **200** – OK
|
||||
- **400** – Bad request (invalid report ID).
|
||||
- **401** - Authentication failed, refer to [Authentication API](/docs/grafana/latest/developers/http_api/auth/).
|
||||
- **404** - Not found (report with this ID does not exist).
|
||||
- **500** - Unexpected error or server misconfiguration. Refer to server logs for more details
|
||||
|
||||
## Send a report
|
||||
|
||||
`POST /api/reports/email`
|
||||
|
||||
Generate and send a report. This API waits for the report to be generated before returning. We recommend that you set the client's timeout to at least 60 seconds.
|
||||
|
||||
#### Required permissions
|
||||
|
||||
See note in the [introduction](#reporting-api) for an explanation.
|
||||
|
||||
| Action | Scope |
|
||||
| ------------ | ----- |
|
||||
| reports:send | n/a |
|
||||
|
||||
### Example request
|
||||
|
||||
```http
|
||||
POST /api/reports/email HTTP/1.1
|
||||
Accept: application/json
|
||||
Content-Type: application/json
|
||||
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
|
||||
|
||||
```
|
||||
|
||||
#### JSON Body Schema
|
||||
|
||||
| Field name | Data type | Description |
|
||||
| ------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
||||
| id | string | ID of the report to send. It is the same as in the URL when editing a report, not to be confused with the ID of the dashboard. Required. |
|
||||
| emails | string | Comma-separated list of emails to which to send the report to. Overrides the emails from the report. Required if `useEmailsFromReport` is not present. |
|
||||
| useEmailsFromReport | boolean | Send the report to the emails specified in the report. Required if `emails` is not present. |
|
||||
|
||||
### Example response
|
||||
|
||||
```http
|
||||
HTTP/1.1 200 OK
|
||||
Content-Type: application/json
|
||||
Content-Length: 29
|
||||
|
||||
```
|
||||
|
||||
### Status Codes
|
||||
|
||||
- **200** – Report was sent.
|
||||
- **400** – Bad request (invalid json, missing content-type, missing or invalid fields, etc.).
|
||||
- **401** - Authentication failed, refer to [Authentication API](/docs/grafana/latest/developers/http_api/auth/).
|
||||
- **403** - Forbidden (access denied to a report or a dashboard used in the report).
|
||||
- **404** - Report not found.
|
||||
- **500** - Unexpected error or server misconfiguration. Refer to server logs for more details.
|
||||
|
||||
## Get reports branding settings
|
||||
|
||||
`GET /api/reports/settings`
|
||||
|
||||
Returns reports branding settings that are global and used across all the reports.
|
||||
|
||||
#### Required permissions
|
||||
|
||||
See note in the [introduction](#reporting-api) for an explanation.
|
||||
|
||||
| Action | Scope |
|
||||
| --------------------- | ----- |
|
||||
| reports.settings:read | n/a |
|
||||
|
||||
### Example request
|
||||
|
||||
```http
|
||||
GET /api/reports/settings HTTP/1.1
|
||||
Accept: application/json
|
||||
Content-Type: application/json
|
||||
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
|
||||
```
|
||||
|
||||
### Example response
|
||||
|
||||
```http
|
||||
HTTP/1.1 200 OK
|
||||
Content-Type: application/json
|
||||
Content-Length: 181
|
||||
|
||||
```
|
||||
|
||||
### Status Codes
|
||||
|
||||
- **200** – OK
|
||||
- **401** - Authentication failed, refer to [Authentication API](/docs/grafana/latest/developers/http_api/auth/).
|
||||
- **500** - Unexpected error or server misconfiguration. Refer to server logs for more detail
|
||||
|
||||
## Save reports branding settings
|
||||
|
||||
`POST /api/reports/settings`
|
||||
|
||||
Creates settings if they don't exist, otherwise updates them. These settings are global and used across all the reports.
|
||||
|
||||
#### Required permissions
|
||||
|
||||
See note in the [introduction](#reporting-api) for an explanation.
|
||||
|
||||
| Action | Scope |
|
||||
| ---------------------- | ----- |
|
||||
| reports.settings:write | n/a |
|
||||
|
||||
### Example request
|
||||
|
||||
```http
|
||||
POST /api/reports/settings HTTP/1.1
|
||||
Accept: application/json
|
||||
Content-Type: application/json
|
||||
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
|
||||
|
||||
```
|
||||
|
||||
#### JSON Body Schema
|
||||
|
||||
| Field name | Data type | Description |
|
||||
| ------------------------ | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| branding.reportLogoUrl | string | URL of an image used as a logo on every page of the report. |
|
||||
| branding.emailLogoUrl | string | URL of an image used as a logo in the email. |
|
||||
| branding.emailFooterMode | string | Can be `sent-by` or `none`.<br/>`sent-by` adds a "Sent by `branding.emailFooterText`" footer link to the email. Requires specifying values in the `branding.emailFooterText` and `branding.emailFooterLink` fields.<br/>`none` suppresses adding a "Sent by" footer link to the email. |
|
||||
| branding.emailFooterText | string | Text of a URL added to the email "Sent by" footer. |
|
||||
| branding.emailFooterLink | string | URL address value added to the email "Sent by" footer. |
|
||||
|
||||
### Example response
|
||||
|
||||
```http
|
||||
HTTP/1.1 200 OK
|
||||
Content-Type: application/json
|
||||
Content-Length: 35
|
||||
|
||||
```
|
||||
|
||||
### Status Codes
|
||||
|
||||
- **200** – OK
|
||||
- **400** – Bad request (invalid json, missing or invalid fields values, etc.).
|
||||
- **401** - Authentication failed, refer to [Authentication API](/docs/grafana/latest/developers/http_api/auth/).
|
||||
- **500** - Unexpected error or server misconfiguration. Refer to server logs for more detail
|
||||
|
||||
## Send a test email
|
||||
|
||||
`POST /api/reports/test-email`
|
||||
|
||||
Sends a test email with a report without persisting it in the database.
|
||||
|
||||
#### Required permissions
|
||||
|
||||
See note in the [introduction](#reporting-api) for an explanation.
|
||||
|
||||
| Action | Scope |
|
||||
| ------------ | ----- |
|
||||
| reports:send | n/a |
|
||||
|
||||
### Example request
|
||||
|
||||
See [JSON body schema](#config-json-body-schema) for fields description.
|
||||
|
||||
```http
|
||||
POST /api/reports/test-email HTTP/1.1
|
||||
Accept: application/json
|
||||
Content-Type: application/json
|
||||
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
|
||||
|
||||
```
|
||||
|
||||
### Example response
|
||||
|
||||
```http
|
||||
HTTP/1.1 200 OK
|
||||
Content-Type: application/json
|
||||
Content-Length: 29
|
||||
|
||||
```
|
||||
|
||||
### Status Codes
|
||||
|
||||
- **200** – OK
|
||||
- **400** – Bad request (invalid json, missing or invalid fields values, etc.).
|
||||
- **401** - Authentication failed, refer to [Authentication API](/docs/grafana/latest/developers/http_api/auth/).
|
||||
- **403** - Forbidden (access denied to a report or a dashboard used in the report).
|
||||
- **500** - Unexpected error or server misconfiguration. Refer to server logs for more details
|
||||
|
||||
`POST /api/reports/email`
|
||||
|
||||
Generate and send a report. This API waits for the report to be generated before returning. We recommend that you set the client's timeout to at least 60 seconds.
|
||||
|
||||
#### Required permissions
|
||||
|
||||
See note in the [introduction](#reporting-api) for an explanation.
|
||||
|
||||
| Action | Scope |
|
||||
| ------------ | ----- |
|
||||
| reports:send | n/a |
|
||||
|
||||
### Example request
|
||||
|
||||
```http
|
||||
POST /api/reports/email HTTP/1.1
|
||||
Accept: application/json
|
||||
Content-Type: application/json
|
||||
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
|
||||
|
||||
{
|
||||
"id":"3",
|
||||
"useEmailsFromReport": true
|
||||
}
|
||||
```
|
||||
|
||||
#### JSON Body Schema
|
||||
|
||||
| Field name | Data type | Description |
|
||||
| ------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
||||
| id | string | ID of the report to send. It is the same as in the URL when editing a report, not to be confused with the ID of the dashboard. Required. |
|
||||
| emails | string | Comma-separated list of emails to which to send the report to. Overrides the emails from the report. Required if `useEmailsFromReport` is not present. |
|
||||
| useEmailsFromReport | boolean | Send the report to the emails specified in the report. Required if `emails` is not present. |
|
||||
|
||||
### Example response
|
||||
|
||||
```http
|
||||
HTTP/1.1 200 OK
|
||||
Content-Type: application/json
|
||||
Content-Length: 29
|
||||
|
||||
{"message":"Report was sent"}
|
||||
```
|
||||
|
||||
### Status Codes
|
||||
|
||||
- **200** – Report was sent.
|
||||
- **400** – Bad request (invalid json, missing content-type, missing or invalid fields, etc.).
|
||||
- **401** - Authentication failed, refer to [Authentication API](/docs/grafana/latest/developers/http_api/auth/).
|
||||
- **403** - Forbidden (access denied to a report or a dashboard used in the report).
|
||||
- **404** - Report not found.
|
||||
- **500** - Unexpected error or server misconfiguration. Refer to server logs for more details.
|
||||
|
||||
## Get reports branding settings
|
||||
|
||||
`GET /api/reports/settings`
|
||||
|
||||
Returns reports branding settings that are global and used across all the reports.
|
||||
|
||||
#### Required permissions
|
||||
|
||||
See note in the [introduction](#reporting-api) for an explanation.
|
||||
|
||||
| Action | Scope |
|
||||
| --------------------- | ----- |
|
||||
| reports.settings:read | n/a |
|
||||
|
||||
### Example request
|
||||
|
||||
```http
|
||||
GET /api/reports/settings HTTP/1.1
|
||||
Accept: application/json
|
||||
Content-Type: application/json
|
||||
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
|
||||
```
|
||||
|
||||
### Example response
|
||||
|
||||
```http
|
||||
HTTP/1.1 200 OK
|
||||
Content-Type: application/json
|
||||
Content-Length: 181
|
||||
|
||||
{
|
||||
"id": 1,
|
||||
"userId": 1,
|
||||
"orgId": 1,
|
||||
"branding": {
|
||||
"reportLogoUrl": "",
|
||||
"emailLogoUrl": "",
|
||||
"emailFooterMode": "sent-by",
|
||||
"emailFooterText": "Grafana Labs",
|
||||
"emailFooterLink": "https://grafana.com/"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Status Codes
|
||||
|
||||
- **200** – OK
|
||||
- **401** - Authentication failed, refer to [Authentication API](/docs/grafana/latest/developers/http_api/auth/).
|
||||
- **500** - Unexpected error or server misconfiguration. Refer to server logs for more detail
|
||||
|
||||
## Save reports branding settings
|
||||
|
||||
`POST /api/reports/settings`
|
||||
|
||||
Creates settings if they don't exist, otherwise updates them. These settings are global and used across all the reports.
|
||||
|
||||
#### Required permissions
|
||||
|
||||
See note in the [introduction](#reporting-api) for an explanation.
|
||||
|
||||
| Action | Scope |
|
||||
| ---------------------- | ----- |
|
||||
| reports.settings:write | n/a |
|
||||
|
||||
### Example request
|
||||
|
||||
```http
|
||||
POST /api/reports/settings HTTP/1.1
|
||||
Accept: application/json
|
||||
Content-Type: application/json
|
||||
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
|
||||
|
||||
{
|
||||
"branding": {
|
||||
"reportLogoUrl": "https://grafana.com/reportLogo.jpg",
|
||||
"emailLogoUrl": "https://grafana.com/emailLogo.jpg",
|
||||
"emailFooterMode": "sent-by",
|
||||
"emailFooterText": "Grafana Labs",
|
||||
"emailFooterLink": "https://grafana.com/"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### JSON Body Schema
|
||||
|
||||
| Field name | Data type | Description |
|
||||
| ------------------------ | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| branding.reportLogoUrl | string | URL of an image used as a logo on every page of the report. |
|
||||
| branding.emailLogoUrl | string | URL of an image used as a logo in the email. |
|
||||
| branding.emailFooterMode | string | Can be `sent-by` or `none`.<br/>`sent-by` adds a "Sent by `branding.emailFooterText`" footer link to the email. Requires specifying values in the `branding.emailFooterText` and `branding.emailFooterLink` fields.<br/>`none` suppresses adding a "Sent by" footer link to the email. |
|
||||
| branding.emailFooterText | string | Text of a URL added to the email "Sent by" footer. |
|
||||
| branding.emailFooterLink | string | URL address value added to the email "Sent by" footer. |
|
||||
|
||||
### Example response
|
||||
|
||||
```http
|
||||
HTTP/1.1 200 OK
|
||||
Content-Type: application/json
|
||||
Content-Length: 35
|
||||
|
||||
{
|
||||
"message": "Report settings saved"
|
||||
}
|
||||
```
|
||||
|
||||
### Status Codes
|
||||
|
||||
- **200** – OK
|
||||
- **400** – Bad request (invalid json, missing or invalid fields values, etc.).
|
||||
- **401** - Authentication failed, refer to [Authentication API](/docs/grafana/latest/developers/http_api/auth/).
|
||||
- **500** - Unexpected error or server misconfiguration. Refer to server logs for more detail
|
||||
|
||||
## Send a test email
|
||||
|
||||
`POST /api/reports/test-email`
|
||||
|
||||
Sends a test email with a report without persisting it in the database.
|
||||
|
||||
#### Required permissions
|
||||
|
||||
See note in the [introduction](#reporting-api) for an explanation.
|
||||
|
||||
| Action | Scope |
|
||||
| ------------ | ----- |
|
||||
| reports:send | n/a |
|
||||
|
||||
### Example request
|
||||
|
||||
See [JSON body schema](#config-json-body-schema) for fields description.
|
||||
|
||||
```http
|
||||
POST /api/reports/test-email HTTP/1.1
|
||||
Accept: application/json
|
||||
Content-Type: application/json
|
||||
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
|
||||
|
||||
{{
|
||||
"name": "Report 4",
|
||||
"recipients": "example-report@grafana.com",
|
||||
"replyTo": "",
|
||||
"message": "Hello, please, find the report attached",
|
||||
"schedule": {
|
||||
"startDate": "2022-10-02T10:00:00+02:00",
|
||||
"endDate": "2022-11-02T20:00:00+02:00",
|
||||
"frequency": "daily",
|
||||
"intervalFrequency": "",
|
||||
"intervalAmount": 0,
|
||||
"workdaysOnly": true,
|
||||
"timeZone": "Europe/Warsaw"
|
||||
},
|
||||
"options": {
|
||||
"orientation": "landscape",
|
||||
"layout": "grid"
|
||||
},
|
||||
"enableDashboardUrl": true,
|
||||
"dashboards": [
|
||||
{
|
||||
"dashboard": {
|
||||
"uid": "7MeksYbmk",
|
||||
},
|
||||
"timeRange": {
|
||||
"from": "2022-08-08T15:00:00+02:00",
|
||||
"to": "2022-09-02T17:00:00+02:00"
|
||||
},
|
||||
"reportVariables": {
|
||||
"variable1": "Value1"
|
||||
}
|
||||
}
|
||||
],
|
||||
"formats": [
|
||||
"pdf",
|
||||
"csv"
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### Example response
|
||||
|
||||
```http
|
||||
HTTP/1.1 200 OK
|
||||
Content-Type: application/json
|
||||
Content-Length: 29
|
||||
|
||||
{
|
||||
"message": "Test email sent"
|
||||
}
|
||||
```
|
||||
|
||||
### Status Codes
|
||||
|
||||
- **200** – OK
|
||||
- **400** – Bad request (invalid json, missing or invalid fields values, etc.).
|
||||
- **401** - Authentication failed, refer to [Authentication API](/docs/grafana/latest/developers/http_api/auth/).
|
||||
- **403** - Forbidden (access denied to a report or a dashboard used in the report).
|
||||
- **500** - Unexpected error or server misconfiguration. Refer to server logs for more details
|
||||
@@ -0,0 +1,376 @@
|
||||
---
|
||||
aliases:
|
||||
- ../../../http_api/serviceaccount/ # /docs/grafana/next/http_api/serviceaccount/
|
||||
- ../../../developers/http_api/serviceaccount/ # /docs/grafana/next/developers/http_api/serviceaccount/
|
||||
canonical: https://grafana.com/docs/grafana/latest/developer-resources/api-reference/http-api/serviceaccount/
|
||||
description: Grafana service account HTTP API
|
||||
keywords:
|
||||
- grafana
|
||||
- http
|
||||
- documentation
|
||||
- api
|
||||
- serviceaccount
|
||||
labels:
|
||||
products:
|
||||
- enterprise
|
||||
- oss
|
||||
- cloud
|
||||
title: Service account HTTP API
|
||||
---
|
||||
|
||||
# Service account API
|
||||
|
||||
> If you are running Grafana Enterprise, for some endpoints you'll need to have specific permissions. Refer to [Role-based access control permissions](/docs/grafana/latest/administration/roles-and-permissions/access-control/custom-role-actions-scopes/) for more information.
|
||||
> For Grafana Cloud instances, please use a Bearer token to authenticate. The examples within this section reference Basic authentication which is for On-Prem Grafana instances.
|
||||
|
||||
## Search service accounts with Paging
|
||||
|
||||
`GET /api/serviceaccounts/search?perpage=10&page=1&query=myserviceaccount`
|
||||
|
||||
**Required permissions**
|
||||
|
||||
See note in the [introduction](#service-account-api) for an explanation.
|
||||
|
||||
| Action | Scope |
|
||||
| -------------------- | ----- |
|
||||
| serviceaccounts:read | n/a |
|
||||
|
||||
**Example Request**:
|
||||
|
||||
```http
|
||||
GET /api/serviceaccounts/search?perpage=10&page=1&query=mygraf HTTP/1.1
|
||||
Accept: application/json
|
||||
Content-Type: application/json
|
||||
Authorization: Basic YWRtaW46YWRtaW4=
|
||||
```
|
||||
|
||||
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 user list E.g. if `totalCount` is equal to 100 users and the `perpage` parameter is set to 10 then there are 10 pages of users. The `query` parameter is optional and it will return results where the query value is contained in one of the `name`. Query values with spaces need to be URL encoded e.g. `query=Jane%20Doe`.
|
||||
|
||||
**Example Response**:
|
||||
|
||||
```http
|
||||
HTTP/1.1 200
|
||||
Content-Type: application/json
|
||||
{
|
||||
```
|
||||
|
||||
## Create service account
|
||||
|
||||
`POST /api/serviceaccounts`
|
||||
|
||||
**Required permissions**
|
||||
|
||||
See note in the [introduction](#service-account-api) for an explanation.
|
||||
|
||||
| Action | Scope |
|
||||
| ---------------------- | ----- |
|
||||
| serviceaccounts:create | n/a |
|
||||
|
||||
**Example Request**:
|
||||
|
||||
```http
|
||||
POST /api/serviceaccounts HTTP/1.1
|
||||
Accept: application/json
|
||||
Content-Type: application/json
|
||||
Authorization: Basic YWRtaW46YWRtaW4=
|
||||
|
||||
```
|
||||
|
||||
**Example Response**:
|
||||
|
||||
```http
|
||||
HTTP/1.1 201
|
||||
Content-Type: application/json
|
||||
|
||||
```
|
||||
|
||||
Fixed and custom roles can be set on service accounts using the [RBAC HTTP API](/docs/grafana/latest/developers/http_api/access_control/#set-user-role-assignments).
|
||||
|
||||
## Get a service account by ID
|
||||
|
||||
`GET /api/serviceaccounts/:id`
|
||||
|
||||
**Required permissions**
|
||||
|
||||
See note in the [introduction](#service-account-api) for an explanation.
|
||||
|
||||
| Action | Scope |
|
||||
| -------------------- | --------------------- |
|
||||
| serviceaccounts:read | serviceaccounts:id:\* |
|
||||
|
||||
**Example Request**:
|
||||
|
||||
```http
|
||||
GET /api/serviceaccounts/1 HTTP/1.1
|
||||
Accept: application/json
|
||||
Content-Type: application/json
|
||||
Authorization: Basic YWRtaW46YWRtaW4=
|
||||
```
|
||||
|
||||
**Example Response**:
|
||||
|
||||
```http
|
||||
HTTP/1.1 200
|
||||
Content-Type: application/json
|
||||
|
||||
```
|
||||
|
||||
## Update service account
|
||||
|
||||
`PATCH /api/serviceaccounts/:id`
|
||||
|
||||
**Required permissions**
|
||||
|
||||
See note in the [introduction](#service-account-api) for an explanation.
|
||||
|
||||
| Action | Scope |
|
||||
| --------------------- | --------------------- |
|
||||
| serviceaccounts:write | serviceaccounts:id:\* |
|
||||
|
||||
**Example Request**:
|
||||
|
||||
```http
|
||||
PATCH /api/serviceaccounts/2 HTTP/1.1
|
||||
Accept: application/json
|
||||
Content-Type: application/json
|
||||
Authorization: Basic YWRtaW46YWRtaW4=
|
||||
|
||||
```
|
||||
|
||||
**Example Response**:
|
||||
|
||||
```http
|
||||
HTTP/1.1 200
|
||||
Content-Type: application/json
|
||||
|
||||
```
|
||||
|
||||
Fixed and custom roles can be set on service accounts using the [RBAC HTTP API](/docs/grafana/latest/developers/http_api/access_control/#set-user-role-assignments).
|
||||
|
||||
## Delete service account
|
||||
|
||||
`DELETE /api/serviceaccounts/:id`
|
||||
|
||||
**Required permissions**
|
||||
|
||||
See note in the [introduction](#service-account-api) for an explanation.
|
||||
|
||||
| Action | Scope |
|
||||
| ---------------------- | --------------------- |
|
||||
| serviceaccounts:delete | serviceaccounts:id:\* |
|
||||
|
||||
**Example Request**:
|
||||
|
||||
```http
|
||||
DELETE /api/serviceaccounts/2 HTTP/1.1
|
||||
Accept: application/json
|
||||
Content-Type: application/json
|
||||
Authorization: Basic YWRtaW46YWRtaW4=
|
||||
```
|
||||
|
||||
**Example Response**:
|
||||
|
||||
```http
|
||||
HTTP/1.1 200
|
||||
Content-Type: application/json
|
||||
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Get service account tokens
|
||||
|
||||
`GET /api/serviceaccounts/:id/tokens`
|
||||
|
||||
**Required permissions**
|
||||
|
||||
See note in the [introduction](#service-account-api) for an explanation.
|
||||
|
||||
| Action | Scope |
|
||||
| -------------------- | --------------------- |
|
||||
| serviceaccounts:read | serviceaccounts:id:\* |
|
||||
|
||||
**Example Request**:
|
||||
|
||||
```http
|
||||
GET /api/serviceaccounts/2/tokens HTTP/1.1
|
||||
Accept: application/json
|
||||
Content-Type: application/json
|
||||
Authorization: Basic YWRtaW46YWRtaW4=
|
||||
```
|
||||
|
||||
**Example Response**:
|
||||
|
||||
```http
|
||||
HTTP/1.1 200
|
||||
Content-Type: application/json
|
||||
|
||||
```
|
||||
|
||||
## Create service account tokens
|
||||
|
||||
`POST /api/serviceaccounts/:id/tokens`
|
||||
|
||||
**Required permissions**
|
||||
|
||||
See note in the [introduction](#service-account-api) for an explanation.
|
||||
|
||||
| Action | Scope |
|
||||
| --------------------- | --------------------- |
|
||||
| serviceaccounts:write | serviceaccounts:id:\* |
|
||||
|
||||
**Example Request**:
|
||||
|
||||
```http
|
||||
POST /api/serviceaccounts/2/tokens HTTP/1.1
|
||||
Accept: application/json
|
||||
Content-Type: application/json
|
||||
Authorization: Basic YWRtaW46YWRtaW4=
|
||||
|
||||
```
|
||||
|
||||
Default value for the `secondsToLive` is 0, which means that the service account token will never expire.
|
||||
|
||||
**Example Response**:
|
||||
|
||||
```http
|
||||
HTTP/1.1 200
|
||||
Content-Type: application/json
|
||||
|
||||
```
|
||||
|
||||
## Delete service account tokens
|
||||
|
||||
`DELETE /api/serviceaccounts/:id/tokens/:tokenId`
|
||||
|
||||
**Required permissions**
|
||||
|
||||
See note in the [introduction](#service-account-api) for an explanation.
|
||||
|
||||
| Action | Scope |
|
||||
| --------------------- | --------------------- |
|
||||
| serviceaccounts:write | serviceaccounts:id:\* |
|
||||
|
||||
**Example Request**:
|
||||
|
||||
```http
|
||||
DELETE /api/serviceaccounts/2/tokens/1 HTTP/1.1
|
||||
Accept: application/json
|
||||
Content-Type: application/json
|
||||
Authorization: Basic YWRtaW46YWRtaW4=
|
||||
```
|
||||
|
||||
**Example Response**:
|
||||
|
||||
```http
|
||||
HTTP/1.1 200
|
||||
Content-Type: application/json
|
||||
|
||||
```
|
||||
|
||||
See note in the [introduction](#service-account-api) for an explanation.
|
||||
|
||||
| Action | Scope |
|
||||
| -------------------- | --------------------- |
|
||||
| serviceaccounts:read | serviceaccounts:id:\* |
|
||||
|
||||
**Example Request**:
|
||||
|
||||
```http
|
||||
GET /api/serviceaccounts/2/tokens HTTP/1.1
|
||||
Accept: application/json
|
||||
Content-Type: application/json
|
||||
Authorization: Basic YWRtaW46YWRtaW4=
|
||||
```
|
||||
|
||||
**Example Response**:
|
||||
|
||||
```http
|
||||
HTTP/1.1 200
|
||||
Content-Type: application/json
|
||||
|
||||
[
|
||||
{
|
||||
"id": 1,
|
||||
"name": "grafana",
|
||||
"role": "Viewer",
|
||||
"created": "2022-03-23T10:31:02Z",
|
||||
"expiration": null,
|
||||
"secondsUntilExpiration": 0,
|
||||
"hasExpired": false
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
## Create service account tokens
|
||||
|
||||
`POST /api/serviceaccounts/:id/tokens`
|
||||
|
||||
**Required permissions**
|
||||
|
||||
See note in the [introduction](#service-account-api) for an explanation.
|
||||
|
||||
| Action | Scope |
|
||||
| --------------------- | --------------------- |
|
||||
| serviceaccounts:write | serviceaccounts:id:\* |
|
||||
|
||||
**Example Request**:
|
||||
|
||||
```http
|
||||
POST /api/serviceaccounts/2/tokens HTTP/1.1
|
||||
Accept: application/json
|
||||
Content-Type: application/json
|
||||
Authorization: Basic YWRtaW46YWRtaW4=
|
||||
|
||||
{
|
||||
"name": "grafana",
|
||||
"secondsToLive": 604800
|
||||
}
|
||||
```
|
||||
|
||||
Default value for the `secondsToLive` is 0, which means that the service account token will never expire.
|
||||
|
||||
**Example Response**:
|
||||
|
||||
```http
|
||||
HTTP/1.1 200
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"id": 7,
|
||||
"name": "grafana",
|
||||
"key": "eyJrIjoiVjFxTHZ6dGdPSjg5Um92MjN1RlhjMkNqYkZUbm9jYkwiLCJuIjoiZ3JhZmFuYSIsImlkIjoxfQ=="
|
||||
}
|
||||
```
|
||||
|
||||
## Delete service account tokens
|
||||
|
||||
`DELETE /api/serviceaccounts/:id/tokens/:tokenId`
|
||||
|
||||
**Required permissions**
|
||||
|
||||
See note in the [introduction](#service-account-api) for an explanation.
|
||||
|
||||
| Action | Scope |
|
||||
| --------------------- | --------------------- |
|
||||
| serviceaccounts:write | serviceaccounts:id:\* |
|
||||
|
||||
**Example Request**:
|
||||
|
||||
```http
|
||||
DELETE /api/serviceaccounts/2/tokens/1 HTTP/1.1
|
||||
Accept: application/json
|
||||
Content-Type: application/json
|
||||
Authorization: Basic YWRtaW46YWRtaW4=
|
||||
```
|
||||
|
||||
**Example Response**:
|
||||
|
||||
```http
|
||||
HTTP/1.1 200
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"message": "API key deleted"
|
||||
}
|
||||
```
|
||||
@@ -0,0 +1,64 @@
|
||||
---
|
||||
aliases:
|
||||
- ../../../http_api/short_url/ # /docs/grafana/next/http_api/short_url/
|
||||
- ../../../developers/http_api/short_url/ # /docs/grafana/next/developers/http_api/short_url/
|
||||
canonical: https://grafana.com/docs/grafana/latest/developer-resources/api-reference/http-api/short_url/
|
||||
description: Grafana Short URL HTTP API
|
||||
keywords:
|
||||
- grafana
|
||||
- http
|
||||
- documentation
|
||||
- api
|
||||
- shortUrl
|
||||
labels:
|
||||
products:
|
||||
- enterprise
|
||||
- oss
|
||||
- cloud
|
||||
title: 'Short URL HTTP API '
|
||||
---
|
||||
|
||||
# Short URL API
|
||||
|
||||
Use this API to create shortened URLs. A short URL represents a longer URL containing complex query parameters in a smaller and simpler format.
|
||||
|
||||
## Create short URL
|
||||
|
||||
`POST /api/short-urls`
|
||||
|
||||
Creates a short URL.
|
||||
|
||||
**Example request:**
|
||||
|
||||
```http
|
||||
POST /api/short-urls HTTP/1.1
|
||||
Accept: application/json
|
||||
Content-Type: application/json
|
||||
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
|
||||
|
||||
```
|
||||
|
||||
JSON body schema:
|
||||
|
||||
- **path** – The path to shorten, relative to the Grafana [root_url](/docs/grafana/latest/setup-grafana/configure-grafana/#root_url).
|
||||
|
||||
**Example response:**
|
||||
|
||||
```http
|
||||
HTTP/1.1 200
|
||||
Content-Type: application/json
|
||||
|
||||
```
|
||||
|
||||
Status codes:
|
||||
|
||||
- **200** – Created
|
||||
- **400** – Errors (invalid JSON, missing or invalid fields)
|
||||
}
|
||||
|
||||
```
|
||||
|
||||
Status codes:
|
||||
|
||||
- **200** – Created
|
||||
- **400** – Errors (invalid JSON, missing or invalid fields)
|
||||
@@ -0,0 +1,234 @@
|
||||
---
|
||||
aliases:
|
||||
- ../../../http_api/snapshot/ # /docs/grafana/next/http_api/snapshot/
|
||||
- ../../../developers/http_api/snapshot/ # /docs/grafana/next/developers/http_api/snapshot/
|
||||
canonical: https://grafana.com/docs/grafana/latest/developer-resources/api-reference/http-api/snapshot/
|
||||
description: Grafana HTTP API
|
||||
keywords:
|
||||
- grafana
|
||||
- http
|
||||
- documentation
|
||||
- api
|
||||
- snapshot
|
||||
labels:
|
||||
products:
|
||||
- enterprise
|
||||
- oss
|
||||
- cloud
|
||||
title: 'Snapshot API'
|
||||
---
|
||||
|
||||
# Snapshot API
|
||||
|
||||
## Create new snapshot
|
||||
|
||||
`POST /api/snapshots`
|
||||
|
||||
**Example Request**:
|
||||
|
||||
```http
|
||||
POST /api/snapshots HTTP/1.1
|
||||
Accept: application/json
|
||||
Content-Type: application/json
|
||||
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
|
||||
|
||||
{
|
||||
"dashboard": {
|
||||
"editable":false,
|
||||
"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. snapshot name
|
||||
- **expires** - Optional. When the snapshot should expire in seconds. 3600 is 1 hour, 86400 is 1 day. Default is never to expire.
|
||||
- **external** - Optional. Save the snapshot on an external server rather than locally. Default is `false`.
|
||||
- **key** - Optional. Define the unique key. Required if **external** is `true`.
|
||||
- **deleteKey** - Optional. Unique key used to delete the snapshot. It is different from the **key** so that only the creator can delete the snapshot. Required if **external** is `true`.
|
||||
|
||||
{{< admonition type="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.
|
||||
{{< /admonition >}}
|
||||
|
||||
**Example Response**:
|
||||
|
||||
```http
|
||||
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** – Key generated to delete the snapshot
|
||||
- **key** – 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. Default is 1000 is not set or provided an invalid value.
|
||||
|
||||
**Example Request**:
|
||||
|
||||
```http
|
||||
GET /api/dashboard/snapshots HTTP/1.1
|
||||
Accept: application/json
|
||||
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
|
||||
```
|
||||
|
||||
**Example Response**:
|
||||
|
||||
```http
|
||||
HTTP/1.1 200
|
||||
Content-Type: application/json
|
||||
|
||||
```
|
||||
|
||||
## Get Snapshot by Key
|
||||
|
||||
`GET /api/snapshots/:key`
|
||||
|
||||
**Example Request**:
|
||||
|
||||
```http
|
||||
GET /api/snapshots/YYYYYYY HTTP/1.1
|
||||
Accept: application/json
|
||||
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
|
||||
```
|
||||
|
||||
**Example Response**:
|
||||
|
||||
```http
|
||||
HTTP/1.1 200
|
||||
Content-Type: application/json
|
||||
|
||||
```
|
||||
|
||||
## Delete Snapshot by Key
|
||||
|
||||
`DELETE /api/snapshots/:key`
|
||||
|
||||
**Example Request**:
|
||||
|
||||
```http
|
||||
DELETE /api/snapshots/YYYYYYY HTTP/1.1
|
||||
Accept: application/json
|
||||
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
|
||||
```
|
||||
|
||||
**Example Response**:
|
||||
|
||||
```http
|
||||
HTTP/1.1 200
|
||||
Content-Type: application/json
|
||||
|
||||
```
|
||||
|
||||
## 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**:
|
||||
|
||||
```http
|
||||
GET /api/snapshots-delete/XXXXXXX HTTP/1.1
|
||||
Accept: application/json
|
||||
```
|
||||
|
||||
**Example Response**:
|
||||
|
||||
```http
|
||||
HTTP/1.1 200
|
||||
Content-Type: application/json
|
||||
|
||||
```
|
||||
]
|
||||
},
|
||||
"time":{
|
||||
},
|
||||
"timezone":"browser",
|
||||
"title":"Home",
|
||||
"version":5
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Delete Snapshot by Key
|
||||
|
||||
`DELETE /api/snapshots/:key`
|
||||
|
||||
**Example Request**:
|
||||
|
||||
```http
|
||||
DELETE /api/snapshots/YYYYYYY HTTP/1.1
|
||||
Accept: application/json
|
||||
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
|
||||
```
|
||||
|
||||
**Example Response**:
|
||||
|
||||
```http
|
||||
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**:
|
||||
|
||||
```http
|
||||
GET /api/snapshots-delete/XXXXXXX HTTP/1.1
|
||||
Accept: application/json
|
||||
```
|
||||
|
||||
**Example Response**:
|
||||
|
||||
```http
|
||||
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}
|
||||
```
|
||||
@@ -0,0 +1,251 @@
|
||||
---
|
||||
aliases:
|
||||
- ../../../http_api/sso-settings/ # /docs/grafana/next/http_api/sso-settings/
|
||||
- ../../../http_api/ssosettings/ # /docs/grafana/next/http_api/ssosettings/
|
||||
- ../../../developers/http_api/sso-settings/ # /docs/grafana/next/developers/http_api/sso-settings/
|
||||
canonical: https://grafana.com/docs/grafana/latest/developer-resources/api-reference/http-api/sso-settings/
|
||||
description: Grafana SSO Settings API
|
||||
keywords:
|
||||
- grafana
|
||||
- http
|
||||
- documentation
|
||||
- api
|
||||
- sso
|
||||
- sso-settings
|
||||
labels:
|
||||
products:
|
||||
- enterprise
|
||||
- oss
|
||||
- cloud
|
||||
title: SSO Settings API
|
||||
---
|
||||
|
||||
# SSO Settings API
|
||||
|
||||
> If you are running Grafana Enterprise, for some endpoints you'll need to have specific permissions. Refer to [Role-based access control permissions](/docs/grafana/latest/administration/roles-and-permissions/access-control/custom-role-actions-scopes/) for more information.
|
||||
|
||||
The API can be used to create, update, delete, get, and list SSO Settings for OAuth2 and SAML.
|
||||
|
||||
The settings managed by this API are stored in the database and override
|
||||
[settings from other sources](/docs/grafana/<GRAFANA_VERSION>/setup-grafana/configure-access/configure-authentication/)
|
||||
(arguments, environment variables, settings file, etc).
|
||||
Therefore, every time settings for a specific provider are removed or reset to the default settings at runtime,
|
||||
the settings are inherited from the other sources in the reverse order of precedence
|
||||
(`arguments > environment variables > settings file`).
|
||||
|
||||
## List SSO Settings
|
||||
|
||||
`GET /api/v1/sso-settings`
|
||||
|
||||
Lists the SSO Settings for all providers.
|
||||
|
||||
The providers or SSO keys that are not managed by this API are retrieved from the other sources (settings file, environment variables, default values).
|
||||
|
||||
**Required permissions**
|
||||
|
||||
See note in the [introduction](#sso-settings) for an explanation.
|
||||
|
||||
| Action | Scope |
|
||||
| --------------- | ---------------------------- |
|
||||
| `settings:read` | `settings:auth.{provider}:*` |
|
||||
|
||||
**Example Request**:
|
||||
|
||||
```http
|
||||
GET /api/v1/sso-settings HTTP/1.1
|
||||
Accept: application/json
|
||||
Content-Type: application/json
|
||||
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
|
||||
```
|
||||
|
||||
**Example Response**:
|
||||
|
||||
```http
|
||||
HTTP/1.1 200
|
||||
Content-Type: application/json
|
||||
[
|
||||
```
|
||||
|
||||
Status Codes:
|
||||
|
||||
- **200** – SSO Settings found
|
||||
- **400** – Bad Request
|
||||
- **401** – Unauthorized
|
||||
- **403** – Access Denied
|
||||
|
||||
## Get SSO Settings
|
||||
|
||||
`GET /api/v1/sso-settings/:provider`
|
||||
|
||||
Gets the SSO Settings for a provider.
|
||||
|
||||
The SSO keys that are not managed by this API are retrieved from the other sources (settings file, environment variables, default values).
|
||||
|
||||
**Required permissions**
|
||||
|
||||
See note in the [introduction](#sso-settings) for an explanation.
|
||||
|
||||
| Action | Scope |
|
||||
| --------------- | ---------------------------- |
|
||||
| `settings:read` | `settings:auth.{provider}:*` |
|
||||
|
||||
**Example Request**:
|
||||
|
||||
```http
|
||||
GET /api/v1/sso-settings/github HTTP/1.1
|
||||
Accept: application/json
|
||||
Content-Type: application/json
|
||||
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
|
||||
```
|
||||
|
||||
**Example Response**:
|
||||
|
||||
```http
|
||||
HTTP/1.1 200
|
||||
Content-Type: application/json
|
||||
ETag: db87f729761898ee
|
||||
{
|
||||
```
|
||||
|
||||
Status Codes:
|
||||
|
||||
- **200** – SSO Settings found
|
||||
- **400** – Bad Request
|
||||
- **401** – Unauthorized
|
||||
- **403** – Access Denied
|
||||
- **404** – SSO Settings not found
|
||||
|
||||
## Update SSO Settings
|
||||
|
||||
`PUT /api/v1/sso-settings/:provider`
|
||||
|
||||
Updates the SSO Settings for a provider.
|
||||
|
||||
When you submit new settings for a provider via API,
|
||||
Grafana verifies whether the given settings are allowed and valid.
|
||||
If they are, then Grafana stores the settings in the database and reloads
|
||||
Grafana services with no need to restart the instance.
|
||||
|
||||
{{< admonition type="note" >}}
|
||||
If you run Grafana in high availability mode, configuration changes
|
||||
may not get applied to all Grafana instances immediately. You may need
|
||||
to wait a few minutes for the configuration to propagate to all Grafana instances.
|
||||
{{< /admonition >}}
|
||||
|
||||
**Required permissions**
|
||||
|
||||
See note in the [introduction](#sso-settings) for an explanation.
|
||||
|
||||
| Action | Scope |
|
||||
| ---------------- | ---------------------------- |
|
||||
| `settings:write` | `settings:auth.{provider}:*` |
|
||||
|
||||
**Example Request**:
|
||||
|
||||
```http
|
||||
PUT /api/v1/sso-settings/github HTTP/1.1
|
||||
Accept: application/json
|
||||
Content-Type: application/json
|
||||
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
|
||||
|
||||
```
|
||||
|
||||
**Example Response**:
|
||||
|
||||
```http
|
||||
HTTP/1.1 204
|
||||
Content-Type: application/json
|
||||
```
|
||||
|
||||
Status Codes:
|
||||
|
||||
- **204** – SSO Settings updated
|
||||
- **400** – Bad Request
|
||||
- **401** – Unauthorized
|
||||
- **403** – Access Denied
|
||||
|
||||
## Delete SSO Settings
|
||||
|
||||
`DELETE /api/v1/sso-settings/:provider`
|
||||
|
||||
Deletes an existing SSO Settings entry for a provider.
|
||||
|
||||
**Required permissions**
|
||||
|
||||
See note in the [introduction](#sso-settings) for an explanation.
|
||||
|
||||
| Action | Scope |
|
||||
| ---------------- | ---------------------------- |
|
||||
| `settings:write` | `settings:auth.{provider}:*` |
|
||||
|
||||
**Example Request**:
|
||||
|
||||
```http
|
||||
DELETE /api/v1/sso-settings/azuread HTTP/1.1
|
||||
Accept: application/json
|
||||
Content-Type: application/json
|
||||
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
|
||||
```
|
||||
|
||||
**Example Response**:
|
||||
|
||||
```http
|
||||
HTTP/1.1 204
|
||||
Content-Type: application/json
|
||||
```
|
||||
|
||||
Status Codes:
|
||||
|
||||
- **204** – SSO Settings deleted
|
||||
- **400** – Bad Request
|
||||
- **401** – Unauthorized
|
||||
- **403** – Access Denied
|
||||
- **404** – SSO Settings not found
|
||||
HTTP/1.1 204
|
||||
Content-Type: application/json
|
||||
```
|
||||
|
||||
Status Codes:
|
||||
|
||||
- **204** – SSO Settings updated
|
||||
- **400** – Bad Request
|
||||
- **401** – Unauthorized
|
||||
- **403** – Access Denied
|
||||
|
||||
## Delete SSO Settings
|
||||
|
||||
`DELETE /api/v1/sso-settings/:provider`
|
||||
|
||||
Deletes an existing SSO Settings entry for a provider.
|
||||
|
||||
**Required permissions**
|
||||
|
||||
See note in the [introduction](#sso-settings) for an explanation.
|
||||
|
||||
| Action | Scope |
|
||||
| ---------------- | ---------------------------- |
|
||||
| `settings:write` | `settings:auth.{provider}:*` |
|
||||
|
||||
**Example Request**:
|
||||
|
||||
```http
|
||||
DELETE /api/v1/sso-settings/azuread HTTP/1.1
|
||||
Accept: application/json
|
||||
Content-Type: application/json
|
||||
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
|
||||
```
|
||||
|
||||
**Example Response**:
|
||||
|
||||
```http
|
||||
HTTP/1.1 204
|
||||
Content-Type: application/json
|
||||
```
|
||||
|
||||
Status Codes:
|
||||
|
||||
- **204** – SSO Settings deleted
|
||||
- **400** – Bad Request
|
||||
- **401** – Unauthorized
|
||||
- **403** – Access Denied
|
||||
- **404** – SSO Settings not found
|
||||
533
docs/sources/developer-resources/api-reference/http-api/team.md
Normal file
533
docs/sources/developer-resources/api-reference/http-api/team.md
Normal file
@@ -0,0 +1,533 @@
|
||||
---
|
||||
aliases:
|
||||
- ../../../http_api/team/ # /docs/grafana/next/http_api/team/
|
||||
- ../../../developers/http_api/team/ # /docs/grafana/next/developers/http_api/team/
|
||||
canonical: https://grafana.com/docs/grafana/latest/developer-resources/api-reference/http-api/team/
|
||||
description: Grafana Team HTTP API
|
||||
keywords:
|
||||
- grafana
|
||||
- http
|
||||
- documentation
|
||||
- api
|
||||
- team
|
||||
- teams
|
||||
- group
|
||||
labels:
|
||||
products:
|
||||
- enterprise
|
||||
- oss
|
||||
- cloud
|
||||
title: Team HTTP API
|
||||
---
|
||||
|
||||
# Team API
|
||||
|
||||
This API can be used to manage Teams and Team Memberships.
|
||||
|
||||
Access to these API endpoints is restricted as follows:
|
||||
|
||||
- All authenticated users are able to view details of teams they are a member of.
|
||||
- Organization Admins are able to manage all teams and team members.
|
||||
|
||||
> If you are running Grafana Enterprise, for some endpoints you'll need to have specific permissions. Refer to [Role-based access control permissions](/docs/grafana/latest/administration/roles-and-permissions/access-control/custom-role-actions-scopes/) for more information.
|
||||
|
||||
## Team Search With Paging
|
||||
|
||||
`GET /api/teams/search?perpage=50&page=1&query=myteam&sort=memberCount-desc`
|
||||
|
||||
or
|
||||
|
||||
`GET /api/teams/search?name=myteam`
|
||||
|
||||
**Required permissions**
|
||||
|
||||
See note in the [introduction](#team-api) for an explanation.
|
||||
|
||||
| Action | Scope |
|
||||
| ---------- | -------- |
|
||||
| teams:read | teams:\* |
|
||||
|
||||
**Example Request**:
|
||||
|
||||
```http
|
||||
GET /api/teams/search?perpage=10&page=1&query=mytestteam HTTP/1.1
|
||||
Accept: application/json
|
||||
Content-Type: application/json
|
||||
Authorization: Bearer glsa_kcVxDhZtu5ISOZIEt
|
||||
```
|
||||
|
||||
**Example Response**:
|
||||
|
||||
```http
|
||||
HTTP/1.1 200
|
||||
Content-Type: application/json
|
||||
|
||||
```
|
||||
|
||||
### Using the query parameter
|
||||
|
||||
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 E.g. if `totalCount` is equal to 100 teams and the `perpage` parameter is set to 10 then there are 10 pages of teams.
|
||||
|
||||
The `query` parameter is optional and it will return results where the query value is contained in the `name` field. Query values with spaces need to be URL encoded e.g. `query=my%20team`.
|
||||
|
||||
The `sort` param is an optional comma separated list of options to order the search result. Accepted values for the sort filter are: ` name-asc`, `name-desc`, `email-asc`, `email-desc`, `memberCount-asc`, `memberCount-desc`. By default, if `sort` is not specified, the teams list will be ordered by `name` in ascending order.
|
||||
|
||||
### Using the name parameter
|
||||
|
||||
The `name` parameter returns a single team if the parameter matches the `name` field.
|
||||
|
||||
#### Status Codes:
|
||||
|
||||
- **200** - Ok
|
||||
- **400** - Bad Request
|
||||
- **401** - Unauthorized
|
||||
- **403** - Permission denied
|
||||
- **404** - Team not found (if searching by name)
|
||||
|
||||
## Get Team By Id
|
||||
|
||||
`GET /api/teams/:id`
|
||||
|
||||
**Required permissions**
|
||||
|
||||
See note in the [introduction](#team-api) for an explanation.
|
||||
|
||||
| Action | Scope |
|
||||
| ---------- | -------- |
|
||||
| teams:read | teams:\* |
|
||||
|
||||
**Example Request**:
|
||||
|
||||
```http
|
||||
GET /api/teams/1 HTTP/1.1
|
||||
Accept: application/json
|
||||
Content-Type: application/json
|
||||
Authorization: Bearer glsa_kcVxDhZtu5ISOZIEt
|
||||
```
|
||||
|
||||
**Example Response**:
|
||||
|
||||
```http
|
||||
HTTP/1.1 200
|
||||
Content-Type: application/json
|
||||
|
||||
```
|
||||
|
||||
Status Codes:
|
||||
|
||||
- **200** - Ok
|
||||
- **401** - Unauthorized
|
||||
- **403** - Permission denied
|
||||
- **404** - Team not found
|
||||
|
||||
## Add Team
|
||||
|
||||
The Team `name` needs to be unique. `name` is required and `email` is optional.
|
||||
|
||||
`POST /api/teams`
|
||||
|
||||
**Required permissions**
|
||||
|
||||
See note in the [introduction](#team-api) for an explanation.
|
||||
|
||||
| Action | Scope |
|
||||
| ------------ | ----- |
|
||||
| teams:create | N/A |
|
||||
|
||||
**Example Request**:
|
||||
|
||||
```http
|
||||
POST /api/teams HTTP/1.1
|
||||
Accept: application/json
|
||||
Content-Type: application/json
|
||||
Authorization: Bearer glsa_kcVxDhZtu5ISOZIEt
|
||||
|
||||
```
|
||||
|
||||
**Example Response**:
|
||||
|
||||
```http
|
||||
HTTP/1.1 200
|
||||
Content-Type: application/json
|
||||
|
||||
```
|
||||
|
||||
Status Codes:
|
||||
|
||||
- **200** - Ok
|
||||
- **401** - Unauthorized
|
||||
- **403** - Permission denied
|
||||
- **409** - Team name is taken
|
||||
|
||||
## Update Team
|
||||
|
||||
There are two fields that can be updated for a team: `name` and `email`.
|
||||
|
||||
`PUT /api/teams/:id`
|
||||
|
||||
**Required permissions**
|
||||
|
||||
See note in the [introduction](#team-api) for an explanation.
|
||||
|
||||
| Action | Scope |
|
||||
| ----------- | -------- |
|
||||
| teams:write | teams:\* |
|
||||
|
||||
**Example Request**:
|
||||
|
||||
```http
|
||||
PUT /api/teams/2 HTTP/1.1
|
||||
Accept: application/json
|
||||
Content-Type: application/json
|
||||
Authorization: Bearer glsa_kcVxDhZtu5ISOZIEt
|
||||
|
||||
```
|
||||
|
||||
**Example Response**:
|
||||
|
||||
```http
|
||||
HTTP/1.1 200
|
||||
Content-Type: application/json
|
||||
|
||||
```
|
||||
|
||||
Status Codes:
|
||||
|
||||
- **200** - Ok
|
||||
- **401** - Unauthorized
|
||||
- **403** - Permission denied
|
||||
- **404** - Team not found
|
||||
- **409** - Team name is taken
|
||||
|
||||
## Delete Team By Id
|
||||
|
||||
`DELETE /api/teams/:id`
|
||||
|
||||
**Required permissions**
|
||||
|
||||
See note in the [introduction](#team-api) for an explanation.
|
||||
|
||||
| Action | Scope |
|
||||
| ------------ | -------- |
|
||||
| teams:delete | teams:\* |
|
||||
|
||||
**Example Request**:
|
||||
|
||||
```http
|
||||
DELETE /api/teams/2 HTTP/1.1
|
||||
Accept: application/json
|
||||
Content-Type: application/json
|
||||
Authorization: Bearer glsa_kcVxDhZtu5ISOZIEt
|
||||
```
|
||||
|
||||
**Example Response**:
|
||||
|
||||
```http
|
||||
HTTP/1.1 200
|
||||
Content-Type: application/json
|
||||
|
||||
```
|
||||
|
||||
Status Codes:
|
||||
|
||||
- **200** - Ok
|
||||
- **401** - Unauthorized
|
||||
- **403** - Permission denied
|
||||
- **404** - Failed to delete Team. ID not found
|
||||
|
||||
## Get Team Members
|
||||
|
||||
`GET /api/teams/:teamId/members`
|
||||
|
||||
**Required permissions**
|
||||
|
||||
See note in the [introduction](#team-api) for an explanation.
|
||||
|
||||
| Action | Scope |
|
||||
| ---------------------- | -------- |
|
||||
| teams.permissions:read | teams:\* |
|
||||
|
||||
**Example Request**:
|
||||
|
||||
```http
|
||||
GET /api/teams/1/members HTTP/1.1
|
||||
Accept: application/json
|
||||
Content-Type: application/json
|
||||
Authorization: Bearer glsa_kcVxDhZtu5ISOZIEt
|
||||
```
|
||||
|
||||
**Example Response**:
|
||||
|
||||
```http
|
||||
HTTP/1.1 200
|
||||
Content-Type: application/json
|
||||
|
||||
```
|
||||
|
||||
Status Codes:
|
||||
|
||||
- **200** - Ok
|
||||
- **401** - Unauthorized
|
||||
- **403** - Permission denied
|
||||
|
||||
## Add Team Member
|
||||
|
||||
`POST /api/teams/:teamId/members`
|
||||
|
||||
**Required permissions**
|
||||
|
||||
See note in the [introduction](#team-api) for an explanation.
|
||||
|
||||
| Action | Scope |
|
||||
| ----------------------- | -------- |
|
||||
| teams.permissions:write | teams:\* |
|
||||
|
||||
**Example Request**:
|
||||
|
||||
```http
|
||||
POST /api/teams/1/members HTTP/1.1
|
||||
Accept: application/json
|
||||
Content-Type: application/json
|
||||
Authorization: Bearer glsa_kcVxDhZtu5ISOZIEt
|
||||
|
||||
```
|
||||
|
||||
**Example Response**:
|
||||
|
||||
```http
|
||||
HTTP/1.1 200
|
||||
Content-Type: application/json
|
||||
|
||||
```
|
||||
|
||||
Status Codes:
|
||||
|
||||
- **200** - Ok
|
||||
- **400** - User is already added to this team
|
||||
- **401** - Unauthorized
|
||||
- **403** - Permission denied
|
||||
- **404** - Team not found
|
||||
|
||||
## Remove Member From Team
|
||||
|
||||
`DELETE /api/teams/:teamId/members/:userId`
|
||||
|
||||
**Required permissions**
|
||||
|
||||
See note in the [introduction](#team-api) for an explanation.
|
||||
|
||||
| Action | Scope |
|
||||
| ----------------------- | -------- |
|
||||
| teams.permissions:write | teams:\* |
|
||||
|
||||
**Example Request**:
|
||||
|
||||
```http
|
||||
DELETE /api/teams/2/members/3 HTTP/1.1
|
||||
Accept: application/json
|
||||
Content-Type: application/json
|
||||
Authorization: Bearer glsa_kcVxDhZtu5ISOZIEt
|
||||
```
|
||||
|
||||
**Example Response**:
|
||||
|
||||
```http
|
||||
HTTP/1.1 200
|
||||
Content-Type: application/json
|
||||
|
||||
```
|
||||
|
||||
Status Codes:
|
||||
|
||||
- **200** - Ok
|
||||
- **401** - Unauthorized
|
||||
- **403** - Permission denied
|
||||
- **404** - Team not found/Team member not found
|
||||
|
||||
## Bulk Update Team Members
|
||||
|
||||
Allows bulk updating team members and administrators using user emails.
|
||||
Will override all current members and administrators for the specified team.
|
||||
|
||||
`PUT /api/teams/:teamId/members
|
||||
|
||||
**Required permissions**
|
||||
|
||||
See note in the [introduction](#team-api) for an explanation.
|
||||
|
||||
| Action | Scope |
|
||||
| ----------------------- | -------- |
|
||||
| teams.permissions:write | teams:\* |
|
||||
|
||||
**Example Request**:
|
||||
|
||||
```http
|
||||
PUT /api/teams/1/members HTTP/1.1
|
||||
Accept: application/json
|
||||
Content-Type: application/json
|
||||
Authorization: Bearer glsa_kcVxDhZtu5ISOZIEt
|
||||
|
||||
{
|
||||
"members": ["user1@email.com", "user2@email.com"]
|
||||
"admins": ["user3@email.com"]
|
||||
}
|
||||
```
|
||||
|
||||
**Example Response**:
|
||||
|
||||
```http
|
||||
HTTP/1.1 200
|
||||
Content-Type: application/json
|
||||
|
||||
{"message":"Team memberships have been updated"}
|
||||
```
|
||||
|
||||
Status Codes:
|
||||
|
||||
- **200** - Ok
|
||||
- **401** - Unauthorized
|
||||
- **403** - Permission denied
|
||||
- **404** - Team not found/Team member not found
|
||||
- **500** - Internal error
|
||||
|
||||
## Get Team Preferences
|
||||
|
||||
`GET /api/teams/:teamId/preferences`
|
||||
|
||||
**Required permissions**
|
||||
|
||||
See note in the [introduction](#team-api) for an explanation.
|
||||
|
||||
| Action | Scope |
|
||||
| ---------- | -------- |
|
||||
| teams:read | teams:\* |
|
||||
|
||||
**Example Request**:
|
||||
|
||||
```http
|
||||
GET /api/teams/2/preferences HTTP/1.1
|
||||
Accept: application/json
|
||||
Content-Type: application/json
|
||||
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
|
||||
```
|
||||
|
||||
**Example Response**:
|
||||
|
||||
```http
|
||||
HTTP/1.1 200
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"theme": "",
|
||||
"homeDashboardId": 0,
|
||||
"homeDashboardUID": "",
|
||||
"timezone": ""
|
||||
}
|
||||
```
|
||||
|
||||
## Update Team Preferences
|
||||
|
||||
`PUT /api/teams/:teamId/preferences`
|
||||
|
||||
**Required permissions**
|
||||
|
||||
See note in the [introduction](#team-api) for an explanation.
|
||||
|
||||
| Action | Scope |
|
||||
| ----------- | -------- |
|
||||
| teams:write | teams:\* |
|
||||
|
||||
**Example Request**:
|
||||
|
||||
```http
|
||||
PUT /api/teams/2/preferences HTTP/1.1
|
||||
Accept: application/json
|
||||
Content-Type: application/json
|
||||
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
|
||||
|
||||
{
|
||||
"theme": "dark",
|
||||
"homeDashboardId": 39,
|
||||
"homeDashboardUID": "jcIIG-07z",
|
||||
"timezone": "utc"
|
||||
}
|
||||
```
|
||||
|
||||
JSON Body Schema:
|
||||
|
||||
- **theme** - One of: `light`, `dark`, or an empty string for the default theme
|
||||
- **homeDashboardId** - Deprecated. Use `homeDashboardUID` instead.
|
||||
- **homeDashboardUID** - The `:uid` of a dashboard
|
||||
- **timezone** - One of: `utc`, `browser`, or an empty string for the default
|
||||
|
||||
Omitting a key will cause the current value to be replaced with the system default value.
|
||||
|
||||
**Example Response**:
|
||||
|
||||
```http
|
||||
HTTP/1.1 200
|
||||
Content-Type: text/plain; charset=utf-8
|
||||
|
||||
{
|
||||
"message":"Preferences updated"
|
||||
}
|
||||
```
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"theme": "",
|
||||
"homeDashboardId": 0,
|
||||
"homeDashboardUID": "",
|
||||
"timezone": ""
|
||||
}
|
||||
```
|
||||
|
||||
## Update Team Preferences
|
||||
|
||||
`PUT /api/teams/:teamId/preferences`
|
||||
|
||||
**Required permissions**
|
||||
|
||||
See note in the [introduction](#team-api) for an explanation.
|
||||
|
||||
| Action | Scope |
|
||||
| ----------- | -------- |
|
||||
| teams:write | teams:\* |
|
||||
|
||||
**Example Request**:
|
||||
|
||||
```http
|
||||
PUT /api/teams/2/preferences HTTP/1.1
|
||||
Accept: application/json
|
||||
Content-Type: application/json
|
||||
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
|
||||
|
||||
{
|
||||
"theme": "dark",
|
||||
"homeDashboardId": 39,
|
||||
"homeDashboardUID": "jcIIG-07z",
|
||||
"timezone": "utc"
|
||||
}
|
||||
```
|
||||
|
||||
JSON Body Schema:
|
||||
|
||||
- **theme** - One of: `light`, `dark`, or an empty string for the default theme
|
||||
- **homeDashboardId** - Deprecated. Use `homeDashboardUID` instead.
|
||||
- **homeDashboardUID** - The `:uid` of a dashboard
|
||||
- **timezone** - One of: `utc`, `browser`, or an empty string for the default
|
||||
|
||||
Omitting a key will cause the current value to be replaced with the system default value.
|
||||
|
||||
**Example Response**:
|
||||
|
||||
```http
|
||||
HTTP/1.1 200
|
||||
Content-Type: text/plain; charset=utf-8
|
||||
|
||||
{
|
||||
"message":"Preferences updated"
|
||||
}
|
||||
```
|
||||
@@ -0,0 +1,202 @@
|
||||
---
|
||||
aliases:
|
||||
- ../../../http_api/external_group_sync/ # /docs/grafana/next/http_api/external_group_sync/
|
||||
- ../../../developers/http_api/external_group_sync/ # /docs/grafana/next/developers/http_api/external_group_sync/
|
||||
- ../../../developers/http_api/team_sync/ # /docs/grafana/next/developers/http_api/team_sync/
|
||||
canonical: https://grafana.com/docs/grafana/latest/developer-resources/api-reference/http-api/team_sync/
|
||||
description: Grafana Team Sync HTTP API
|
||||
keywords:
|
||||
- grafana
|
||||
- http
|
||||
- documentation
|
||||
- api
|
||||
- team
|
||||
- teams
|
||||
- group
|
||||
- member
|
||||
- enterprise
|
||||
labels:
|
||||
products:
|
||||
- enterprise
|
||||
- oss
|
||||
- cloud
|
||||
title: Team Sync HTTP API
|
||||
---
|
||||
|
||||
# Team Sync API
|
||||
|
||||
> Team Sync is only available in Grafana Enterprise. Read more about [Grafana Enterprise](/docs/grafana/latest/introduction/grafana-enterprise/).
|
||||
|
||||
> If you are running Grafana Enterprise, for some endpoints you'll need to have specific permissions. Refer to [Role-based access control permissions](/docs/grafana/latest/administration/roles-and-permissions/access-control/custom-role-actions-scopes/) for more information.
|
||||
|
||||
## Get External Groups
|
||||
|
||||
`GET /api/teams/:teamId/groups`
|
||||
|
||||
**Required permissions**
|
||||
|
||||
See note in the [introduction](#external-group-synchronization-api) for an explanation.
|
||||
|
||||
| Action | Scope |
|
||||
| ---------------------- | -------- |
|
||||
| teams.permissions:read | teams:\* |
|
||||
|
||||
**Example Request**:
|
||||
|
||||
```http
|
||||
GET /api/teams/1/groups HTTP/1.1
|
||||
Accept: application/json
|
||||
Content-Type: application/json
|
||||
Authorization: Bearer glsa_kcVxDhZtu5ISOZIEt
|
||||
```
|
||||
|
||||
**Example Response**:
|
||||
|
||||
```http
|
||||
HTTP/1.1 200
|
||||
Content-Type: application/json
|
||||
|
||||
```
|
||||
|
||||
Status Codes:
|
||||
|
||||
- **200** - Ok
|
||||
- **401** - Unauthorized
|
||||
- **403** - Permission denied
|
||||
|
||||
## Add External Group
|
||||
|
||||
`POST /api/teams/:teamId/groups`
|
||||
|
||||
**Required permissions**
|
||||
|
||||
See note in the [introduction](#external-group-synchronization-api) for an explanation.
|
||||
|
||||
| Action | Scope |
|
||||
| ----------------------- | -------- |
|
||||
| teams.permissions:write | teams:\* |
|
||||
|
||||
**Example Request**:
|
||||
|
||||
```http
|
||||
POST /api/teams/1/groups HTTP/1.1
|
||||
Accept: application/json
|
||||
Content-Type: application/json
|
||||
Authorization: Bearer YWRtaW46YWRtaW4=
|
||||
|
||||
```
|
||||
|
||||
**Example Response**:
|
||||
|
||||
```http
|
||||
HTTP/1.1 200
|
||||
Content-Type: application/json
|
||||
|
||||
```
|
||||
|
||||
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=external-group-id`
|
||||
|
||||
**Required permissions**
|
||||
|
||||
See note in the [introduction](#external-group-synchronization-api) for an explanation.
|
||||
|
||||
| Action | Scope |
|
||||
| ----------------------- | -------- |
|
||||
| teams.permissions:write | teams:\* |
|
||||
|
||||
**Example Request**:
|
||||
|
||||
```http
|
||||
DELETE /api/teams/1/groups?groupId=cn%3Deditors%2Cou%3Dgroups%2Cdc%3Dgrafana%2Cdc%3Dorg HTTP/1.1
|
||||
Accept: application/json
|
||||
Content-Type: application/json
|
||||
Authorization: Bearer glsa_kcVxDhZtu5ISOZIEt
|
||||
```
|
||||
|
||||
**Example Response**:
|
||||
|
||||
```http
|
||||
HTTP/1.1 200
|
||||
Content-Type: application/json
|
||||
|
||||
```
|
||||
|
||||
Status Codes:
|
||||
|
||||
- **200** - Ok
|
||||
- **401** - Unauthorized
|
||||
- **403** - Permission denied
|
||||
- **404** - Team not found/Group not found
|
||||
|
||||
## Search Team Groups
|
||||
|
||||
`GET /api/teams/:teamId/groups/search`
|
||||
|
||||
Search for team groups with pagination support.
|
||||
|
||||
**Required permissions**
|
||||
|
||||
| Action | Scope |
|
||||
| ---------------------- | -------- |
|
||||
| teams.permissions:read | teams:\* |
|
||||
|
||||
**Example Request**:
|
||||
|
||||
```http
|
||||
GET /api/teams/1/groups/search?name=editors&query=group&page=1&perpage=10 HTTP/1.1
|
||||
Accept: application/json
|
||||
Content-Type: application/json
|
||||
Authorization: Bearer glsa_kcVxDhZtu5ISOZIEt
|
||||
```
|
||||
|
||||
**Example Response**:
|
||||
|
||||
```http
|
||||
HTTP/1.1 200
|
||||
Content-Type: application/json
|
||||
|
||||
```
|
||||
|
||||
Status Codes:
|
||||
|
||||
- **200** - Ok
|
||||
- **400** - Bad Request (invalid team ID format or missing query parameter)
|
||||
- **401** - Unauthorized
|
||||
- **403** - Permission denied
|
||||
- **500** - Internal Server Error
|
||||
HTTP/1.1 200
|
||||
Content-Type: application/json
|
||||
|
||||
[
|
||||
{
|
||||
"totalCount": 1,
|
||||
"teamGroups": [
|
||||
{
|
||||
"orgId": 1,
|
||||
"teamId": 1,
|
||||
"groupId": "cn=editors,ou=groups,dc=grafana,dc=org"
|
||||
}
|
||||
],
|
||||
"page": 1,
|
||||
"perPage": 10
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
Status Codes:
|
||||
|
||||
- **200** - Ok
|
||||
- **400** - Bad Request (invalid team ID format or missing query parameter)
|
||||
- **401** - Unauthorized
|
||||
- **403** - Permission denied
|
||||
- **500** - Internal Server Error
|
||||
701
docs/sources/developer-resources/api-reference/http-api/user.md
Normal file
701
docs/sources/developer-resources/api-reference/http-api/user.md
Normal file
@@ -0,0 +1,701 @@
|
||||
---
|
||||
aliases:
|
||||
- ../../../http_api/user/ # /docs/grafana/next/http_api/user/
|
||||
- ../../../developers/http_api/user/ # /docs/grafana/next/developers/http_api/user/
|
||||
canonical: https://grafana.com/docs/grafana/latest/developer-resources/api-reference/http-api/user/
|
||||
description: Grafana User HTTP API
|
||||
keywords:
|
||||
- grafana
|
||||
- http
|
||||
- documentation
|
||||
- api
|
||||
- user
|
||||
labels:
|
||||
products:
|
||||
- enterprise
|
||||
- oss
|
||||
- cloud
|
||||
title: User HTTP API
|
||||
refs:
|
||||
role-based-access-control-permissions:
|
||||
- pattern: /docs/grafana/
|
||||
destination: /docs/grafana/<GRAFANA_VERSION>/administration/roles-and-permissions/access-control/custom-role-actions-scopes/
|
||||
- pattern: /docs/grafana-cloud/
|
||||
destination: /docs/grafana/<GRAFANA_VERSION>/administration/roles-and-permissions/access-control/custom-role-actions-scopes/
|
||||
---
|
||||
|
||||
# User API
|
||||
|
||||
{{< admonition type="caution" >}}
|
||||
You can't authenticate to the User HTTP API with service account tokens.
|
||||
Service accounts are limited to an organization and an organization role.
|
||||
They can't be granted [Grafana server administrator permissions](/docs/grafana/<GRAFANA_VERSION>/administration/roles-and-permissions/#grafana-server-administrators).
|
||||
|
||||
Alternatively, you can use the [Organization HTTP API](/docs/grafana/<GRAFANA_VERSION>/developers/http_api/org/#current-organization-api) with service account tokens to manage users in a specific organization
|
||||
|
||||
To use these API endpoints you have to use Basic authentication and the Grafana user must have the Grafana server administrator permission.
|
||||
|
||||
The `admin` user that Grafana is provisioned with by default has permissions to use these API endpoints.
|
||||
{{< /admonition >}}
|
||||
|
||||
For Grafana Cloud customers, refer to [Organization HTTP API](/docs/grafana/latest/developers/http_api/org/) for finding users with the org Admin role.
|
||||
|
||||
> If you are running Grafana Enterprise, for some endpoints you'll need to have specific permissions. Refer to [Role-based access control permissions](ref:role-based-access-control-permissions) for more information.
|
||||
|
||||
## Search Users
|
||||
|
||||
`GET /api/users?perpage=10&page=1&sort=login-asc,email-asc`
|
||||
|
||||
**Required permissions**
|
||||
|
||||
See note in the [introduction](#user-api) for an explanation.
|
||||
|
||||
| Action | Scope |
|
||||
| ---------- | --------------- |
|
||||
| users:read | global.users:\* |
|
||||
|
||||
**Example Request**:
|
||||
|
||||
```http
|
||||
GET /api/users HTTP/1.1
|
||||
Accept: application/json
|
||||
Content-Type: application/json
|
||||
Authorization: Basic YWRtaW46YWRtaW4=
|
||||
```
|
||||
|
||||
Default value for the `perpage` parameter is `1000` and for the `page` parameter is `1`. Requires basic authentication and that the authenticated user is a Grafana Admin.
|
||||
|
||||
The `sort` param is an optional comma separated list of options to order the search result. Accepted values for the sort filter are: `login-asc`, `login-desc`, `email-asc`, `email-desc`, `name-asc`, `name-desc`, `lastSeenAtAge-asc`, `lastSeenAtAge-desc`. By default, if `sort` is not specified, the user list will be ordered by `login`, `email` in ascending order.
|
||||
|
||||
**Example Response**:
|
||||
|
||||
```http
|
||||
HTTP/1.1 200
|
||||
Content-Type: application/json
|
||||
|
||||
```
|
||||
|
||||
## Search Users with Paging
|
||||
|
||||
`GET /api/users/search?perpage=10&page=1&query=mygraf&sort=login-asc,email-asc`
|
||||
|
||||
**Required permissions**
|
||||
|
||||
See note in the [introduction](#user-api) for an explanation.
|
||||
|
||||
| Action | Scope |
|
||||
| ---------- | --------------- |
|
||||
| users:read | global.users:\* |
|
||||
|
||||
**Example Request**:
|
||||
|
||||
```http
|
||||
GET /api/users/search?perpage=10&page=1&query=mygraf HTTP/1.1
|
||||
Accept: application/json
|
||||
Content-Type: application/json
|
||||
Authorization: Basic YWRtaW46YWRtaW4=
|
||||
```
|
||||
|
||||
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 user list E.g. if `totalCount` is equal to 100 users and the `perpage` parameter is set to 10 then there are 10 pages of users. The `query` parameter is optional and it will return results where the query value is contained in one of the `name`, `login` or `email` fields. Query values with spaces need to be URL encoded e.g. `query=Jane%20Doe`.
|
||||
|
||||
The `sort` param is an optional comma separated list of options to order the search result. Accepted values for the sort filter are: `login-asc`, `login-desc`, `email-asc`, `email-desc`, `name-asc`, `name-desc`, `lastSeenAtAge-asc`, `lastSeenAtAge-desc`. By default, if `sort` is not specified, the user list will be ordered by `login`, `email` in ascending order.
|
||||
|
||||
Requires basic authentication and that the authenticated user is a Grafana Admin.
|
||||
|
||||
**Example Response**:
|
||||
|
||||
```http
|
||||
HTTP/1.1 200
|
||||
Content-Type: application/json
|
||||
{
|
||||
```
|
||||
|
||||
## Get single user by Id
|
||||
|
||||
`GET /api/users/:id`
|
||||
|
||||
**Required permissions**
|
||||
|
||||
See note in the [introduction](#user-api) for an explanation.
|
||||
|
||||
| Action | Scope |
|
||||
| ---------- | --------------- |
|
||||
| users:read | global.users:\* |
|
||||
|
||||
**Example Request**:
|
||||
|
||||
```http
|
||||
GET /api/users/1 HTTP/1.1
|
||||
Accept: application/json
|
||||
Content-Type: application/json
|
||||
Authorization: Basic YWRtaW46YWRtaW4=
|
||||
```
|
||||
|
||||
Requires basic authentication and that the authenticated user is a Grafana Admin.
|
||||
|
||||
**Example Response**:
|
||||
|
||||
```http
|
||||
HTTP/1.1 200
|
||||
Content-Type: application/json
|
||||
|
||||
```
|
||||
|
||||
## Get single user by Username(login) or Email
|
||||
|
||||
`GET /api/users/lookup?loginOrEmail=user@mygraf.com`
|
||||
|
||||
**Required permissions**
|
||||
|
||||
See note in the [introduction](#user-api) for an explanation.
|
||||
|
||||
| Action | Scope |
|
||||
| ---------- | --------------- |
|
||||
| users:read | global.users:\* |
|
||||
|
||||
**Example Request using the email as option**:
|
||||
|
||||
```http
|
||||
GET /api/users/lookup?loginOrEmail=user@mygraf.com HTTP/1.1
|
||||
Accept: application/json
|
||||
Content-Type: application/json
|
||||
Authorization: Basic YWRtaW46YWRtaW4=
|
||||
```
|
||||
|
||||
**Example Request using the username as option**:
|
||||
|
||||
```http
|
||||
GET /api/users/lookup?loginOrEmail=admin HTTP/1.1
|
||||
Accept: application/json
|
||||
Content-Type: application/json
|
||||
Authorization: Basic YWRtaW46YWRtaW4=
|
||||
```
|
||||
|
||||
Requires basic authentication and that the authenticated user is a Grafana Admin.
|
||||
|
||||
**Example Response**:
|
||||
|
||||
```http
|
||||
HTTP/1.1 200
|
||||
Content-Type: application/json
|
||||
|
||||
```
|
||||
|
||||
## User Update
|
||||
|
||||
`PUT /api/users/:id`
|
||||
|
||||
**Required permissions**
|
||||
|
||||
See note in the [introduction](#user-api) for an explanation.
|
||||
|
||||
| Action | Scope |
|
||||
| ----------- | --------------- |
|
||||
| users:write | global.users:\* |
|
||||
|
||||
**Example Request**:
|
||||
|
||||
```http
|
||||
PUT /api/users/2 HTTP/1.1
|
||||
Accept: application/json
|
||||
Content-Type: application/json
|
||||
Authorization: Basic YWRtaW46YWRtaW4=
|
||||
|
||||
```
|
||||
|
||||
Requires basic authentication and that the authenticated user is a Grafana Admin.
|
||||
|
||||
**Example Response**:
|
||||
|
||||
```http
|
||||
HTTP/1.1 200
|
||||
Content-Type: application/json
|
||||
|
||||
```
|
||||
|
||||
## Get Organizations for user
|
||||
|
||||
`GET /api/users/:id/orgs`
|
||||
|
||||
**Required permissions**
|
||||
|
||||
See note in the [introduction](#user-api) for an explanation.
|
||||
|
||||
| Action | Scope |
|
||||
| ---------- | --------------- |
|
||||
| users:read | global.users:\* |
|
||||
|
||||
**Example Request**:
|
||||
|
||||
```http
|
||||
GET /api/users/1/orgs HTTP/1.1
|
||||
Accept: application/json
|
||||
Content-Type: application/json
|
||||
Authorization: Basic YWRtaW46YWRtaW4=
|
||||
```
|
||||
|
||||
Requires basic authentication and that the authenticated user is a Grafana Admin.
|
||||
|
||||
**Example Response**:
|
||||
|
||||
```http
|
||||
HTTP/1.1 200
|
||||
Content-Type: application/json
|
||||
|
||||
```
|
||||
|
||||
## Get Teams for user
|
||||
|
||||
`GET /api/users/:id/teams`
|
||||
|
||||
**Required permissions**
|
||||
|
||||
See note in the [introduction](#user-api) for an explanation.
|
||||
|
||||
| Action | Scope |
|
||||
| ---------- | --------------- |
|
||||
| users:read | global.users:\* |
|
||||
| teams:read | teams:\* |
|
||||
|
||||
**Example Request**:
|
||||
|
||||
```http
|
||||
GET /api/users/1/teams HTTP/1.1
|
||||
Accept: application/json
|
||||
Content-Type: application/json
|
||||
Authorization: Basic YWRtaW46YWRtaW4=
|
||||
```
|
||||
|
||||
Requires basic authentication and that the authenticated user is a Grafana Admin.
|
||||
|
||||
**Example Response**:
|
||||
|
||||
```http
|
||||
HTTP/1.1 200
|
||||
Content-Type: application/json
|
||||
|
||||
```
|
||||
|
||||
## User
|
||||
|
||||
## Actual User
|
||||
|
||||
`GET /api/user`
|
||||
|
||||
**Example Request**:
|
||||
|
||||
```http
|
||||
GET /api/user HTTP/1.1
|
||||
Accept: application/json
|
||||
Content-Type: application/json
|
||||
Authorization: Basic YWRtaW46YWRtaW4=
|
||||
```
|
||||
|
||||
Requires basic authentication.
|
||||
|
||||
**Example Response**:
|
||||
|
||||
```http
|
||||
HTTP/1.1 200
|
||||
Content-Type: application/json
|
||||
|
||||
```
|
||||
|
||||
## Change Password
|
||||
|
||||
`PUT /api/user/password`
|
||||
|
||||
Changes the password for the user. Requires basic authentication.
|
||||
|
||||
**Example Request**:
|
||||
|
||||
```http
|
||||
PUT /api/user/password HTTP/1.1
|
||||
Accept: application/json
|
||||
Content-Type: application/json
|
||||
Authorization: Basic YWRtaW46YWRtaW4=
|
||||
|
||||
```
|
||||
|
||||
**Example Response**:
|
||||
|
||||
```http
|
||||
HTTP/1.1 200
|
||||
Content-Type: application/json
|
||||
|
||||
```
|
||||
|
||||
**Change Password with a Script**
|
||||
|
||||
If you need to change a password with a script, here is an example of changing the Admin password using curl with basic auth:
|
||||
|
||||
```bash
|
||||
curl -X PUT -H "Content-Type: application/json" -d '{
|
||||
"oldPassword": "oldpass",
|
||||
"newPassword": "newpass",
|
||||
"confirmNew": "newpass"
|
||||
}' http://admin:oldpass@<your_grafana_host>:3000/api/user/password
|
||||
```
|
||||
|
||||
## Switch user context for a specified user
|
||||
|
||||
`POST /api/users/:userId/using/:organizationId`
|
||||
|
||||
Switch user context to the given organization. Requires basic authentication and that the authenticated user is a Grafana Admin.
|
||||
|
||||
**Example Request**:
|
||||
|
||||
```http
|
||||
POST /api/users/7/using/2 HTTP/1.1
|
||||
Authorization: Basic YWRtaW46YWRtaW4=
|
||||
```
|
||||
|
||||
**Example Response**:
|
||||
|
||||
```http
|
||||
HTTP/1.1 200
|
||||
Content-Type: application/json
|
||||
|
||||
```
|
||||
|
||||
## Switch user context for signed in user
|
||||
|
||||
`POST /api/user/using/:organizationId`
|
||||
|
||||
Switch user context to the given organization.
|
||||
|
||||
**Example Request**:
|
||||
|
||||
```http
|
||||
POST /api/user/using/2 HTTP/1.1
|
||||
Accept: application/json
|
||||
Content-Type: application/json
|
||||
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
|
||||
```
|
||||
|
||||
**Example Response**:
|
||||
|
||||
```http
|
||||
HTTP/1.1 200
|
||||
Content-Type: application/json
|
||||
|
||||
```
|
||||
|
||||
## Organizations of the actual User
|
||||
|
||||
`GET /api/user/orgs`
|
||||
|
||||
Return a list of all organizations of the current user. Requires basic authentication.
|
||||
|
||||
**Example Request**:
|
||||
|
||||
```http
|
||||
GET /api/user/orgs HTTP/1.1
|
||||
Accept: application/json
|
||||
Content-Type: application/json
|
||||
Authorization: Basic YWRtaW46YWRtaW4=
|
||||
```
|
||||
|
||||
**Example Response**:
|
||||
|
||||
```http
|
||||
HTTP/1.1 200
|
||||
Content-Type: application/json
|
||||
|
||||
```
|
||||
|
||||
## Teams that the actual User is member of
|
||||
|
||||
`GET /api/user/teams`
|
||||
|
||||
Return a list of all teams that the current user is member of.
|
||||
|
||||
**Example Request**:
|
||||
|
||||
```http
|
||||
GET /api/user/teams HTTP/1.1
|
||||
Accept: application/json
|
||||
Content-Type: application/json
|
||||
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
|
||||
```
|
||||
|
||||
**Example Response**:
|
||||
|
||||
```http
|
||||
HTTP/1.1 200
|
||||
Content-Type: application/json
|
||||
|
||||
```
|
||||
|
||||
## Star a dashboard
|
||||
|
||||
`POST /api/user/stars/dashboard/uid/:uid`
|
||||
|
||||
Stars the given Dashboard for the actual user.
|
||||
|
||||
**Example Request**:
|
||||
|
||||
```http
|
||||
POST /api/user/stars/dashboard/uid/BqokFhx7z HTTP/1.1
|
||||
Accept: application/json
|
||||
Content-Type: application/json
|
||||
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
|
||||
```
|
||||
|
||||
**Example Response**:
|
||||
|
||||
```http
|
||||
HTTP/1.1 200
|
||||
Content-Type: application/json
|
||||
|
||||
```
|
||||
|
||||
## Unstar a dashboard
|
||||
|
||||
`DELETE /api/user/stars/dashboard/uid/:uid`
|
||||
|
||||
Deletes the starring of the given Dashboard for the actual user.
|
||||
|
||||
**Example Request**:
|
||||
|
||||
```http
|
||||
DELETE /api/user/stars/dashboard/uid/BqokFhx7z HTTP/1.1
|
||||
Accept: application/json
|
||||
Content-Type: application/json
|
||||
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
|
||||
```
|
||||
|
||||
**Example Response**:
|
||||
|
||||
```http
|
||||
HTTP/1.1 200
|
||||
Content-Type: application/json
|
||||
|
||||
```
|
||||
|
||||
## Auth tokens of the actual User
|
||||
|
||||
`GET /api/user/auth-tokens`
|
||||
|
||||
Return a list of all auth tokens (devices) that the actual user currently have logged in from.
|
||||
|
||||
**Example Request**:
|
||||
|
||||
```http
|
||||
GET /api/user/auth-tokens HTTP/1.1
|
||||
Accept: application/json
|
||||
Content-Type: application/json
|
||||
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
|
||||
```
|
||||
|
||||
**Example Response**:
|
||||
|
||||
```http
|
||||
HTTP/1.1 200
|
||||
Content-Type: application/json
|
||||
|
||||
```
|
||||
|
||||
## 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) will no longer be logged in
|
||||
and will be required to authenticate again upon next activity.
|
||||
|
||||
**Example Request**:
|
||||
|
||||
```http
|
||||
POST /api/user/revoke-auth-token HTTP/1.1
|
||||
Accept: application/json
|
||||
Content-Type: application/json
|
||||
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
|
||||
|
||||
```
|
||||
|
||||
**Example Response**:
|
||||
|
||||
```http
|
||||
HTTP/1.1 200
|
||||
Content-Type: application/json
|
||||
|
||||
```
|
||||
Content-Type: application/json
|
||||
Authorization: Basic YWRtaW46YWRtaW4=
|
||||
```
|
||||
|
||||
**Example Response**:
|
||||
|
||||
```http
|
||||
HTTP/1.1 200
|
||||
Content-Type: application/json
|
||||
|
||||
[
|
||||
{
|
||||
"orgId":1,
|
||||
"name":"Main Org.",
|
||||
"role":"Admin"
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
## Teams that the actual User is member of
|
||||
|
||||
`GET /api/user/teams`
|
||||
|
||||
Return a list of all teams that the current user is member of.
|
||||
|
||||
**Example Request**:
|
||||
|
||||
```http
|
||||
GET /api/user/teams HTTP/1.1
|
||||
Accept: application/json
|
||||
Content-Type: application/json
|
||||
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
|
||||
```
|
||||
|
||||
**Example Response**:
|
||||
|
||||
```http
|
||||
HTTP/1.1 200
|
||||
Content-Type: application/json
|
||||
|
||||
[
|
||||
{
|
||||
"id": 1,
|
||||
"orgId": 1,
|
||||
"name": "MyTestTeam",
|
||||
"email": "",
|
||||
"avatarUrl": "\/avatar\/3f49c15916554246daa714b9bd0ee398",
|
||||
"memberCount": 1
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
## Star a dashboard
|
||||
|
||||
`POST /api/user/stars/dashboard/uid/:uid`
|
||||
|
||||
Stars the given Dashboard for the actual user.
|
||||
|
||||
**Example Request**:
|
||||
|
||||
```http
|
||||
POST /api/user/stars/dashboard/uid/BqokFhx7z HTTP/1.1
|
||||
Accept: application/json
|
||||
Content-Type: application/json
|
||||
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
|
||||
```
|
||||
|
||||
**Example Response**:
|
||||
|
||||
```http
|
||||
HTTP/1.1 200
|
||||
Content-Type: application/json
|
||||
|
||||
{"message":"Dashboard starred!"}
|
||||
```
|
||||
|
||||
## Unstar a dashboard
|
||||
|
||||
`DELETE /api/user/stars/dashboard/uid/:uid`
|
||||
|
||||
Deletes the starring of the given Dashboard for the actual user.
|
||||
|
||||
**Example Request**:
|
||||
|
||||
```http
|
||||
DELETE /api/user/stars/dashboard/uid/BqokFhx7z HTTP/1.1
|
||||
Accept: application/json
|
||||
Content-Type: application/json
|
||||
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
|
||||
```
|
||||
|
||||
**Example Response**:
|
||||
|
||||
```http
|
||||
HTTP/1.1 200
|
||||
Content-Type: application/json
|
||||
|
||||
{"message":"Dashboard unstarred"}
|
||||
```
|
||||
|
||||
## Auth tokens of the actual User
|
||||
|
||||
`GET /api/user/auth-tokens`
|
||||
|
||||
Return a list of all auth tokens (devices) that the actual user currently have logged in from.
|
||||
|
||||
**Example Request**:
|
||||
|
||||
```http
|
||||
GET /api/user/auth-tokens HTTP/1.1
|
||||
Accept: application/json
|
||||
Content-Type: application/json
|
||||
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
|
||||
```
|
||||
|
||||
**Example Response**:
|
||||
|
||||
```http
|
||||
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) will no longer be logged in
|
||||
and will be required to authenticate again upon next activity.
|
||||
|
||||
**Example Request**:
|
||||
|
||||
```http
|
||||
POST /api/user/revoke-auth-token HTTP/1.1
|
||||
Accept: application/json
|
||||
Content-Type: application/json
|
||||
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
|
||||
|
||||
{
|
||||
"authTokenId": 364
|
||||
}
|
||||
```
|
||||
|
||||
**Example Response**:
|
||||
|
||||
```http
|
||||
HTTP/1.1 200
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"message": "User auth token revoked"
|
||||
}
|
||||
```
|
||||
Reference in New Issue
Block a user