opensource/grafana
1
0
Fork 0
mirror of https://github.com/grafana/grafana.git synced 2025-07-29 21:32:28 +08:00
Code Issues Packages Projects Releases Wiki Activity

PackageJson: Prettify markdown/mdx on commit with lint-staged (#37616)

Browse Source 
* Format md,mdx files with prettier on lint-staged

* Manually run prettier on docs/sources
This commit is contained in:
Connor Lindsey
2021-08-06 07:52:36 -06:00
committed by GitHub
parent e9c032f10f
commit b78a67cec7
301 changed files with 3216 additions and 2980 deletions
Download Patch File Download Diff File Expand all files Collapse all files

1
docs/sources/http_api/_index.md
View File

@ -42,4 +42,3 @@ Grafana Enterprise includes all of the Grafana OSS APIs as well as those that fo
- [External Group Sync API]({{< relref "external_group_sync.md" >}})
- [License API]({{< relref "licensing.md" >}})
- [Reporting API]({{< relref "reporting.md" >}})

246
docs/sources/http_api/access_control.md
View File

@ -9,7 +9,7 @@ aliases = ["/docs/grafana/latest/http_api/accesscontrol/"]
> Fine-grained access control API is only available in Grafana Enterprise. Read more about [Grafana Enterprise]({{< relref "../enterprise" >}}).
The API can be used to create, update, get and list roles, and create or remove built-in role assignments.
The API can be used to create, update, get and list roles, and create or remove built-in role assignments.
To use the API, you would need to [enable fine-grained access control]({{< relref "../enterprise/access-control/_index.md#enable-fine-grained-access-control" >}}).
The API does not currently work with an API Token. So in order to use these API endpoints you will have to use [Basic auth]({{< relref "./auth/#basic-auth" >}}).
@ -22,9 +22,9 @@ Returns an indicator to check if fine-grained access control is enabled or not.
### Required permissions
Action | Scope
--- | --- |
status:accesscontrol | services:accesscontrol
| Action | Scope |
| -------------------- | ---------------------- |
| status:accesscontrol | services:accesscontrol |
#### Example request
@ -47,12 +47,12 @@ Content-Type: application/json; charset=UTF-8
| Code | Description |
| ---- | ---------------------------------------------------------------------------------- |
| 200 | Returned a flag indicating if the fine-grained access control is enabled or no. |
403 | Access denied
404 | Not found, an indication that fine-grained access control is not available at all.
500 | Unexpected error. Refer to body and/or server logs for more details.
## Create and manage custom roles
| 403 | Access denied |
| 404 | Not found, an indication that fine-grained access control is not available at all. |
| 500 | Unexpected error. Refer to body and/or server logs for more details. |
## Create and manage custom roles
### Get all roles
`GET /api/access-control/roles`
@ -60,14 +60,14 @@ Code | Description
Gets all existing roles. The response contains all global and organization local roles, for the organization which user is signed in.
Refer to the [Role scopes]({{< relref "../enterprise/access-control/roles.md#built-in-role-assignments" >}}) for more information.
#### Required permissions
#### Required permissions
| Action | Scope |
| ---------- | -------- |
| roles:list | roles:\* |
#### Example request
#### Example request
```http
GET /api/access-control/roles
Accept: application/json
@ -107,11 +107,11 @@ Content-Type: application/json; charset=UTF-8
```http
GET /api/access-control/roles/PYnDO3rMk
Accept: application/json
Content-Type: application/json
```
#### Example response
Content-Type: application/json
```
#### Example response
```http
HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
@ -121,9 +121,9 @@ Get a role for the given UID.
#### Status codes
| Code | Description |
--- | --- |
200 | Role is returned.
403 | Access denied
| ---- | -------------------------------------------------------------------- |
| 200 | Role is returned. |
| 403 | Access denied |
| 500 | Unexpected error. Refer to body and/or server logs for more details. |
### Create a new custom role
@ -166,11 +166,11 @@ Content-Type: application/json; charset=UTF-8
#### JSON body schema
| Field Name | Date Type | Required | Description |
--- | --- | --- | ---
uid | string | No | UID of the role. If not present, the UID will be automatically created for you and returned in response. Refer to the [Custom roles]({{< relref "../enterprise/access-control/roles.md#custom-roles" >}}) for more information.
global | boolean | No | A flag indicating if the role is global or not. If set to `false`, the default org ID of the authenticated user will be used from the request. Refer to the [Role scopes]({{< relref "../enterprise/access-control/roles.md#role-scopes" >}}) for more information.
version | number | No | Version of the role. If not present, version 0 will be assigned to the role and returned in the response. Refer to the [Custom roles]({{< relref "../enterprise/access-control/roles.md#custom-roles" >}}) for more information.
name | string | Yes | Name of the role. Refer to [Custom roles]({{< relref "../enterprise/access-control/roles.md#custom-roles" >}}) for more information.
| ----------- | ---------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| uid | string | No | UID of the role. If not present, the UID will be automatically created for you and returned in response. Refer to the [Custom roles]({{< relref "../enterprise/access-control/roles.md#custom-roles" >}}) for more information. |
| global | boolean | No | A flag indicating if the role is global or not. If set to `false`, the default org ID of the authenticated user will be used from the request. Refer to the [Role scopes]({{< relref "../enterprise/access-control/roles.md#role-scopes" >}}) for more information. |
| version | number | No | Version of the role. If not present, version 0 will be assigned to the role and returned in the response. Refer to the [Custom roles]({{< relref "../enterprise/access-control/roles.md#custom-roles" >}}) for more information. |
| name | string | Yes | Name of the role. Refer to [Custom roles]({{< relref "../enterprise/access-control/roles.md#custom-roles" >}}) for more information. |
| description | string | No | Description of the role. |
| permissions | Permission | No | If not present, the role will be created without any permissions. |
@ -183,9 +183,9 @@ Creates a new custom role and maps given permissions to that role. Note that rol
#### Example response
```http
HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
```http
HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
```
@ -211,21 +211,21 @@ Content-Type: application/json
| Action | Scope |
| ----------- | -------------------- |
roles:write | permissions:delegate
#### Example request
```http
PUT /api/access-control/roles/jZrmlLCGka
Accept: application/json
Content-Type: application/json
| roles:write | permissions:delegate |
#### Example request
```http
PUT /api/access-control/roles/jZrmlLCGka
Accept: application/json
Content-Type: application/json
{
"version": 2,
"name": "custom:delete:create:roles",
"description": "My custom role which gives users permissions to delete and create roles",
"permissions": [
{
"name": "custom:delete:create:roles",
"description": "My custom role which gives users permissions to delete and create roles",
"permissions": [
{
"action": "roles:delete",
"scope": "permissions:delegate"
},
@ -254,12 +254,12 @@ Content-Type: application/json; charset=UTF-8
| scope | string | No | If not present, no scope will be mapped to the permission. Refer to [Permissions]({{< relref "../enterprise/access-control/permissions.md#scope-definitions" >}}) for full list of available scopes. |
#### Example response
```http
HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
```
```http
HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
```
#### Status codes
@ -272,9 +272,9 @@ Update the role with the given UID, and it's permissions with the given UID. The
| 500 | Unexpected error. Refer to body and/or server logs for more details. |
### Delete a custom role
`DELETE /api/access-control/roles/:uid?force=false`
`DELETE /api/access-control/roles/:uid?force=false`
Delete a role with the given UID, and it's permissions. If the role is assigned to a built-in role, the deletion operation will fail, unless `force` query param is set to `true`, and in that case all assignments will also be deleted.
#### Required permissions
@ -284,9 +284,9 @@ Accept: application/json
| Action | Scope |
| ------------ | -------------------- |
roles:delete | permissions:delegate
| roles:delete | permissions:delegate |
#### Example request
#### Example request
```http
DELETE /api/access-control/roles/jZrmlLCGka?force=true
@ -302,19 +302,19 @@ Content-Type: application/json
#### Example response
```http
HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
```
#### Status codes
HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
```
#### Status codes
| Code | Description |
| ---- | ---------------------------------------------------------------------------------- |
200 | Role is deleted.
400 | Bad request (invalid json, missing content-type, missing or invalid fields, etc.).
403 | Access denied
500 | Unexpected error. Refer to body and/or server logs for more details.
| 200 | Role is deleted. |
| 400 | Bad request (invalid json, missing content-type, missing or invalid fields, etc.). |
| 403 | Access denied |
| 500 | Unexpected error. Refer to body and/or server logs for more details. |
## Create and remove built-in role assignments
@ -323,9 +323,9 @@ HTTP/1.1 200 OK
### Get all built-in role assignments
`GET /api/access-control/builtin-roles`
Gets all built-in role assignments.
#### Required permissions
| Action | Scope |
@ -347,13 +347,13 @@ Content-Type: application/json; charset=UTF-8
Content-Type: application/json; charset=UTF-8
```
#### Status codes
Code | Description
--- | --- |
200 | Built-in role assignments are returned.
403 | Access denied
#### Status codes
| Code | Description |
| ---- | -------------------------------------------------------------------- |
| 200 | Built-in role assignments are returned. |
| 403 | Access denied |
| 500 | Unexpected error. Refer to body and/or server logs for more details. |
### Create a built-in role assignment
@ -366,9 +366,9 @@ Delete a role with the given UID, and it's permissions. If the role is assigned
`permission:delegate` scope ensures that users can only create built-in role assignments with the roles which have same, or a subset of permissions which the user has.
For example, if a user does not have required permissions for creating users, they won't be able to create a built-in role assignment which will allow to do that. This is done to prevent escalation of privileges.
Action | Scope
--- | --- |
| Action | Scope |
| ----------------- | -------------------- |
| roles.builtin:add | permissions:delegate |
#### Example request
@ -379,9 +379,9 @@ Accept: application/json
Content-Type: application/json
{
"roleUid": "LPMGN99Mk",
"builtinRole": "Grafana Admin",
"global": false
"roleUid": "LPMGN99Mk",
"builtinRole": "Grafana Admin",
"global": false
}
```
@ -396,16 +396,16 @@ Content-Type: application/json; charset=UTF-8
#### Example response
```http
HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
```
#### Status codes
HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
```
#### Status codes
| Code | Description |
| ---- | ---------------------------------------------------------------------------------- |
200 | Role was assigned to built-in role.
| 200 | Role was assigned to built-in role. |
| 400 | Bad request (invalid json, missing content-type, missing or invalid fields, etc.). |
| 403 | Access denied |
| 404 | Role not found |
@ -415,9 +415,9 @@ Gets all built-in role assignments.
`DELETE /api/access-control/builtin-roles/:builtinRole/roles/:roleUID`
Deletes a built-in role assignment (for one of _Viewer_, _Editor_, _Admin_, or _Grafana Admin_) to the role with the provided UID.
#### Required permissions
Deletes a built-in role assignment (for one of _Viewer_, _Editor_, _Admin_, or _Grafana Admin_) to the role with the provided UID.
#### Required permissions
`permission:delegate` scope ensures that users can only remove built-in role assignments with the roles which have same, or a subset of permissions which the user has.
For example, if a user does not have required permissions for creating users, they won't be able to remove a built-in role assignment which allows to do that.
@ -470,11 +470,11 @@ Content-Type: application/json; charset=UTF-8
#### Status codes
Code | Description
--- | --- |
200 | Built-in role assignments are returned.
403 | Access denied
500 | Unexpected error. Refer to body and/or server logs for more details.
| Code | Description |
| ---- | -------------------------------------------------------------------- |
| 200 | Built-in role assignments are returned. |
| 403 | Access denied |
| 500 | Unexpected error. Refer to body and/or server logs for more details. |
### Create a built-in role assignment
@ -484,12 +484,12 @@ Creates a new built-in role assignment.
#### Required permissions
`permission:delegate` scope ensures that users can only create built-in role assignments with the roles which have same, or a subset of permissions which the user has.
`permission:delegate` scope ensures that users can only create built-in role assignments with the roles which have same, or a subset of permissions which the user has.
For example, if a user does not have required permissions for creating users, they won't be able to create a built-in role assignment which will allow to do that. This is done to prevent escalation of privileges.
Action | Scope
--- | --- |
roles.builtin:add | permissions:delegate
| Action | Scope |
| ----------------- | -------------------- |
| roles.builtin:add | permissions:delegate |
#### Example request
@ -507,11 +507,11 @@ Content-Type: application/json
#### JSON body schema
Field Name | Date Type | Required | Description
--- | --- | --- | ---
roleUid | string | Yes | UID of the role.
builtinRole | boolean | Yes | Can be one of `Viewer`, `Editor`, `Admin` or `Grafana Admin`.
global | boolean | No | A flag indicating if the assignment is global or not. If set to `false`, the default org ID of the authenticated user will be used from the request to create organization local assignment. Refer to the [Built-in role assignments]({{< relref "../enterprise/access-control/roles.md#built-in-role-assignments" >}}) for more information.
| Field Name | Date Type | Required | Description |
| ----------- | --------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| roleUid | string | Yes | UID of the role. |
| builtinRole | boolean | Yes | Can be one of `Viewer`, `Editor`, `Admin` or `Grafana Admin`. |
| global | boolean | No | A flag indicating if the assignment is global or not. If set to `false`, the default org ID of the authenticated user will be used from the request to create organization local assignment. Refer to the [Built-in role assignments]({{< relref "../enterprise/access-control/roles.md#built-in-role-assignments" >}}) for more information. |
#### Example response
@ -526,13 +526,13 @@ Content-Type: application/json; charset=UTF-8
#### Status codes
Code | Description
--- | --- |
200 | Role was assigned to built-in role.
400 | Bad request (invalid json, missing content-type, missing or invalid fields, etc.).
403 | Access denied
404 | Role not found
500 | Unexpected error. Refer to body and/or server logs for more details.
| Code | Description |
| ---- | ---------------------------------------------------------------------------------- |
| 200 | Role was assigned to built-in role. |
| 400 | Bad request (invalid json, missing content-type, missing or invalid fields, etc.). |
| 403 | Access denied |
| 404 | Role not found |
| 500 | Unexpected error. Refer to body and/or server logs for more details. |
### Remove a built-in role assignment
@ -545,9 +545,9 @@ Deletes a built-in role assignment (for one of _Viewer_, _Editor_, _Admin_, or _
`permission:delegate` scope ensures that users can only remove built-in role assignments with the roles which have same, or a subset of permissions which the user has.
For example, if a user does not have required permissions for creating users, they won't be able to remove a built-in role assignment which allows to do that.
Action | Scope
--- | --- |
roles.builtin:remove | permissions:delegate
| Action | Scope |
| -------------------- | -------------------- |
| roles.builtin:remove | permissions:delegate |
#### Example request
@ -558,9 +558,9 @@ Accept: application/json
#### Query parameters
Param | Type | Required | Description
--- | --- | --- | ---
global | boolean | No | A flag indicating if the assignment is global or not. If set to `false`, the default org ID of the authenticated user will be used from the request to remove assignment. Refer to the [Built-in role assignments]({{< relref "../enterprise/access-control/roles.md#built-in-role-assignments" >}}) for more information.
| Param | Type | Required | Description |
| ------ | ------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| global | boolean | No | A flag indicating if the assignment is global or not. If set to `false`, the default org ID of the authenticated user will be used from the request to remove assignment. Refer to the [Built-in role assignments]({{< relref "../enterprise/access-control/roles.md#built-in-role-assignments" >}}) for more information. |
#### Example response
@ -575,10 +575,10 @@ Content-Type: application/json; charset=UTF-8
#### Status codes
Code | Description
--- | --- |
200 | Role was unassigned from built-in role.
400 | Bad request (invalid json, missing content-type, missing or invalid fields, etc.).
403 | Access denied
404 | Role not found.
500 | Unexpected error. Refer to body and/or server logs for more details.
| Code | Description |
| ---- | ---------------------------------------------------------------------------------- |
| 200 | Role was unassigned from built-in role. |
| 400 | Bad request (invalid json, missing content-type, missing or invalid fields, etc.). |
| 403 | Access denied |
| 404 | Role not found. |
| 500 | Unexpected error. Refer to body and/or server logs for more details. |

68
docs/sources/http_api/admin.md
View File

@ -12,7 +12,7 @@ the permission of server admin, only users can be given that permission. So in o
must have the Grafana Admin permission. (The default admin user is called `admin` and has permission to use this API.)
> If you are running Grafana Enterprise and have [Fine-grained access control]({{< relref "../enterprise/access-control/_index.md" >}}) enabled, for some endpoints you would need to have relevant permissions.
Refer to specific resources to understand what permissions are required.
> Refer to specific resources to understand what permissions are required.
## Fetch settings
@ -24,9 +24,9 @@ Only works with Basic Authentication (username and password). See [introduction]
See note in the [introduction]({{< ref "#admin-api" >}}) for an explanation.
Action | Scope
--- | --- |
settings:read | settings:**<br>settings:auth.saml:*<br>settings:auth.saml:enabled (property level)
| Action | Scope |
| ------------- | ----------------------------------------------------------------------------------- |
| settings:read | settings:\*_<br>settings:auth.saml:_<br>settings:auth.saml:enabled (property level) |
**Example Request**:
@ -196,9 +196,9 @@ This endpoint only supports changes to `auth.saml` configuration.
## Permissions
`PUT /api/admin/users/:id/permissions`
Only works with Basic Authentication (username and password). See [introduction](http://docs.grafana.org/http_api/admin/#admin-api) for an explanation.
`PUT /api/admin/users/:id/permissions`
Only works with Basic Authentication (username and password). See [introduction](http://docs.grafana.org/http_api/admin/#admin-api) for an explanation.
#### Required permissions
@ -250,9 +250,9 @@ Only works with Basic Authentication (username and password). See [introduction]
**Example Response**:
```http
HTTP/1.1 200
Content-Type: application/json
HTTP/1.1 200
Content-Type: application/json
```
## Pause all alerts
@ -292,9 +292,9 @@ Create new user. Only works with Basic Authentication (username and password). S
#### Required permissions
See note in the [introduction]({{< ref "#admin-api" >}}) for an explanation.
Action | Scope
See note in the [introduction]({{< ref "#admin-api" >}}) for an explanation.
| Action | Scope |
| -------------------- | --------------- |
| users.authtoken:list | global:users:\* |
@ -334,9 +334,9 @@ Change password for a specific user.
**Example Request**:
```http
POST /api/admin/users/1/revoke-auth-token HTTP/1.1
Accept: application/json
Content-Type: application/json
POST /api/admin/users/1/revoke-auth-token HTTP/1.1
Accept: application/json
Content-Type: application/json
```
@ -367,9 +367,9 @@ Only works with Basic Authentication (username and password). See [introduction]
**Example Request**:
```http
POST /api/admin/users/1/logout HTTP/1.1
Accept: application/json
```http
POST /api/admin/users/1/logout HTTP/1.1
Accept: application/json
Content-Type: application/json
```
@ -400,9 +400,9 @@ Only works with Basic Authentication (username and password). See [introduction]
Only works with Basic Authentication (username and password). See [introduction](http://docs.grafana.org/http_api/admin/#admin-api) for an explanation.
#### Required permissions
See note in the [introduction]({{< ref "#admin-api" >}}) for an explanation.
See note in the [introduction]({{< ref "#admin-api" >}}) for an explanation.
| Action | Scope | Provision entity |
| ------------------- | --------------------- | ---------------- |
| provisioning:reload | service:accesscontrol | accesscontrol |
@ -468,9 +468,9 @@ Only works with Basic Authentication (username and password). See [introduction]
See note in the [introduction]({{< ref "#admin-api" >}}) for an explanation.
Action | Scope
--- | --- |
users.authtoken:list | global:users:*
| Action | Scope |
| -------------------- | --------------- |
| users.authtoken:list | global:users:\* |
**Example Request**:
@ -527,9 +527,9 @@ Only works with Basic Authentication (username and password). See [introduction]
See note in the [introduction]({{< ref "#admin-api" >}}) for an explanation.
Action | Scope
--- | --- |
users.authtoken:update | global:users:*
| Action | Scope |
| ---------------------- | --------------- |
| users.authtoken:update | global:users:\* |
**Example Request**:
@ -567,9 +567,9 @@ Only works with Basic Authentication (username and password). See [introduction]
See note in the [introduction]({{< ref "#admin-api" >}}) for an explanation.
Action | Scope
--- | --- |
users.logout | global:users:*
| Action | Scope |
| ------------ | --------------- |
| users.logout | global:users:\* |
**Example Request**:
@ -612,9 +612,9 @@ Only works with Basic Authentication (username and password). See [introduction]
See note in the [introduction]({{< ref "#admin-api" >}}) for an explanation.
Action | Scope | Provision entity
--- | --- | ---
provisioning:reload | service:accesscontrol | accesscontrol
| Action | Scope | Provision entity |
| ------------------- | --------------------- | ---------------- |
| provisioning:reload | service:accesscontrol | accesscontrol |
**Example Request**:

26
docs/sources/http_api/alerting.md
View File

@ -7,9 +7,9 @@ aliases = ["/docs/grafana/latest/http_api/alerting/"]
# Alerting API
>**Note:** This topic is relevant for the [legacy dashboard alerts]({{< relref "../alerting/old-alerting/_index.md" >}}) only.
> **Note:** This topic is relevant for the [legacy dashboard alerts]({{< relref "../alerting/old-alerting/_index.md" >}}) only.
You can find Grafana 8 alerts API specification details [here](https://editor.swagger.io/?url=https://raw.githubusercontent.com/grafana/grafana/main/pkg/services/ngalert/api/tooling/post.json). Also, refer to [Grafana 8 alerts documentation]({{< relref "../alerting/unified-alerting/_index.md" >}}) for details on how to create and manage new alerts.
You can find Grafana 8 alerts API specification details [here](https://editor.swagger.io/?url=https://raw.githubusercontent.com/grafana/grafana/main/pkg/services/ngalert/api/tooling/post.json). Also, refer to [Grafana 8 alerts documentation]({{< relref "../alerting/unified-alerting/_index.md" >}}) for details on how to create and manage new alerts.
You can use the Alerting API to get information about legacy dashboard alerts and their states but this API cannot be used to modify the alert.
To create new alerts or modify them you need to update the dashboard JSON that contains the alerts.
@ -26,21 +26,21 @@ Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
```
Querystring Parameters:
These parameters are used as querystring parameters. For example:
Querystring Parameters:
`/api/alerts?dashboardId=1`
These parameters are used as querystring parameters. For example:
- **dashboardId** – Limit response to alerts in specified dashboard(s). You can specify multiple dashboards, e.g. dashboardId=23&dashboardId=35.
- **panelId** – Limit response to alert for a specified panel on a dashboard.
- **query** - Limit response to alerts having a name like this value.
- **state** - Return alerts with one or more of the following alert states: `ALL`,`no_data`, `paused`, `alerting`, `ok`, `pending`. To specify multiple states use the following format: `?state=paused&state=alerting`
- **limit** - Limit response to *X* number of alerts.
- **folderId** – Limit response to alerts of dashboards in specified folder(s). You can specify multiple folders, e.g. folderId=23&folderId=35.
- **dashboardQuery** - Limit response to alerts having a dashboard name like this value.
- **dashboardTag** - Limit response to alerts of dashboards with specified tags. To do an "AND" filtering with multiple tags, specify the tags parameter multiple times e.g. dashboardTag=tag1&dashboardTag=tag2.
`/api/alerts?dashboardId=1`
- **dashboardId** – Limit response to alerts in specified dashboard(s). You can specify multiple dashboards, e.g. dashboardId=23&dashboardId=35.
- **panelId** – Limit response to alert for a specified panel on a dashboard.
- **query** - Limit response to alerts having a name like this value.
- **state** - Return alerts with one or more of the following alert states: `ALL`,`no_data`, `paused`, `alerting`, `ok`, `pending`. To specify multiple states use the following format: `?state=paused&state=alerting`
- **limit** - Limit response to _X_ number of alerts.
- **folderId** – Limit response to alerts of dashboards in specified folder(s). You can specify multiple folders, e.g. folderId=23&folderId=35.
- **dashboardQuery** - Limit response to alerts having a dashboard name like this value.
- **dashboardTag** - Limit response to alerts of dashboards with specified tags. To do an "AND" filtering with multiple tags, specify the tags parameter multiple times e.g. dashboardTag=tag1&dashboardTag=tag2.
**Example Response**:

9
docs/sources/http_api/annotations.md
View File

@ -86,9 +86,9 @@ Content-Type: application/json
```http
POST /api/annotations/graphite HTTP/1.1
Accept: application/json
Accept: application/json
Content-Type: application/json
```
**Example Response**:
@ -122,8 +122,8 @@ Content-Type: application/json
Content-Type: application/json
```
## Patch Annotation
## Patch Annotation
> This is available in Grafana 6.0.0-beta2 and above.
@ -193,6 +193,7 @@ Content-Type: application/json
- `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

6
docs/sources/http_api/auth.md
View File

@ -13,7 +13,7 @@ Currently you can authenticate via an `API Token` or via a `Session cookie` (acq
## 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.
**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**:
@ -31,13 +31,13 @@ Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
If basic auth is enabled (it is enabled by default), then you can authenticate your HTTP request via
standard basic auth. Basic auth will also authenticate LDAP users.
curl example:
```bash
?curl http://admin:admin@localhost:3000/api/org
{"id":1,"name":"Main Org."}
```
## Create API Token
Open the sidemenu and click the organization dropdown and select the `API Keys` option.
@ -64,6 +64,7 @@ The `Authorization` header value should be `Bearer <your api key>`.
?curl http://api_key:eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk@localhost:3000/api/org
{"id":1,"name":"Main Org."}
```
# Auth HTTP resources / actions
## Api Keys
@ -160,6 +161,7 @@ Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
```
**Example Response**:
```http

70
docs/sources/http_api/create-api-tokens-for-org.md
View File

@ -21,30 +21,34 @@ There are two authentication methods to access the API:
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](http://docs.grafana.org/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.
```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](http://docs.grafana.org/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
```
```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](http://docs.grafana.org/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>
```
```bash
curl -X POST http://admin:admin@localhost:3000/api/user/using/<id of new org>
```
1. [Create the API token](http://docs.grafana.org/http_api/auth/#create-api-key):
```bash
curl -X POST -H "Content-Type: application/json" -d '{"name":"apikeycurl", "role": "Admin"}' http://admin:admin@localhost:3000/api/auth/keys
```
This should return a response: `{"name":"apikeycurl","key":"eyJrIjoiR0ZXZmt1UFc0OEpIOGN5RWdUalBJTllUTk83VlhtVGwiLCJuIjoiYXBpa2V5Y3VybCIsImlkIjo2fQ=="}`.
```bash
curl -X POST -H "Content-Type: application/json" -d '{"name":"apikeycurl", "role": "Admin"}' http://admin:admin@localhost:3000/api/auth/keys
```
Save the key returned here in your password manager as it is not possible to fetch again it in the future.
This should return a response: `{"name":"apikeycurl","key":"eyJrIjoiR0ZXZmt1UFc0OEpIOGN5RWdUalBJTllUTk83VlhtVGwiLCJuIjoiYXBpa2V5Y3VybCIsImlkIjo2fQ=="}`.
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
@ -52,22 +56,22 @@ Using the Token that was created in the previous step, you can create a dashboar
1. [Add a dashboard](http://docs.grafana.org/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
```
```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.
> **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.

2
docs/sources/http_api/curl-examples.md
View File

@ -18,4 +18,4 @@ Here’s a cURL command that works for getting the home dashboard when you are r
```
curl http://admin:admin@localhost:3000/api/search
```
```

3
docs/sources/http_api/dashboard.md
View File

@ -251,7 +251,7 @@ There can be different reasons for this:
- A dashboard with the same uid already exists, `status=name-exists`
- The dashboard belongs to plugin `<plugin title>`, `status=plugin-dashboard`
The response body will have the following properties:
The response body will have the following properties:
```http
HTTP/1.1 412 Precondition Failed
@ -438,4 +438,5 @@ Content-Type: application/json
```
## Dashboard Search
See [Folder/Dashboard Search API]({{< relref "folder_dashboard_search.md" >}}).

4
docs/sources/http_api/data_source.md
View File

@ -5,7 +5,6 @@ keywords = ["grafana", "http", "documentation", "api", "data source"]
aliases = ["/docs/grafana/latest/http_api/datasource/"]
+++
# Data source API
## Get all data sources
@ -293,6 +292,7 @@ Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
POST /api/tsdb/query HTTP/1.1
Accept: application/json
Content-Type: application/json
```
**Example MySQL time series query response:**
@ -528,6 +528,7 @@ Content-Type: application/json
]
}
```
> **Note:** The `from`, `to`, and `queries` properties are required.
JSON Body schema:
@ -564,6 +565,7 @@ Content-Type: application/json
```
**Example MySQL time series query response:**
```http
HTTP/1.1 200
Content-Type: application/json

2
docs/sources/http_api/folder.md
View File

@ -220,7 +220,7 @@ There can be different reasons for this:
Content-Type: application/json
```
Status Codes:
- **200** – Found

62
docs/sources/http_api/org.md
View File

@ -12,7 +12,7 @@ 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 and have [Fine-grained access control]({{< relref "../enterprise/access-control/_index.md" >}}) enabled, for some endpoints you would need to have relevant permissions.
Refer to specific resources to understand what permissions are required.
> Refer to specific resources to understand what permissions are required.
## Current Organization API
@ -52,9 +52,9 @@ Accessible to users with org admin role.
| -------------- | -------- |
| org.users:read | users:\* |
**Example Request**:
```http
**Example Request**:
```http
GET /api/org/users HTTP/1.1
Accept: application/json
Content-Type: application/json
@ -126,9 +126,9 @@ Content-Type: application/json
```
### Delete user in current organization
`DELETE /api/org/users/:userId`
`DELETE /api/org/users/:userId`
#### Required permissions
See note in the [introduction]({{< ref "#organization-api" >}}) for an explanation.
@ -160,9 +160,9 @@ Content-Type: application/json
**Example Request**:
```http
PUT /api/org HTTP/1.1
Accept: application/json
```http
PUT /api/org HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
@ -218,9 +218,9 @@ Adds a global user to the current organization.
### Get Organization by Id
`GET /api/orgs/:orgId`
Only works with Basic Authentication (username and password), see [introduction](#admin-organizations-api).
`GET /api/orgs/:orgId`
Only works with Basic Authentication (username and password), see [introduction](#admin-organizations-api).
**Example Request**:
@ -286,6 +286,7 @@ Content-Type: application/json
HTTP/1.1 200
Content-Type: application/json
```
### Search all Organizations
@ -337,9 +338,11 @@ Content-Type: application/json
Content-Type: application/json
```
### Delete Organization
Only works with Basic Authentication (username and password), see [introduction](#admin-organizations-api).
`DELETE /api/orgs/:orgId`
Only works with Basic Authentication (username and password), see [introduction](#admin-organizations-api).
**Example Request**:
@ -366,6 +369,7 @@ GET /api/orgs HTTP/1.1
#### Required permissions
See note in the [introduction]({{< ref "#organization-api" >}}) for an explanation.
| Action | Scope |
| -------------- | -------- |
| org.users:read | users:\* |
@ -389,7 +393,7 @@ Content-Type: application/json
[
```
### Add User in Organization
### Add User in Organization
`POST /api/orgs/:orgId/users`
@ -445,9 +449,9 @@ Only works with Basic Authentication (username and password), see [introduction]
**Example Response**:
```http
HTTP/1.1 200
Content-Type: application/json
```http
HTTP/1.1 200
Content-Type: application/json
```
@ -456,10 +460,10 @@ GET /api/orgs/1/users HTTP/1.1
`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]({{< ref "#organization-api" >}}) for an explanation.
See note in the [introduction]({{< ref "#organization-api" >}}) for an explanation.
| Action | Scope |
| ---------------- | -------- |
@ -486,9 +490,9 @@ Only works with Basic Authentication (username and password), see [introduction]
See note in the [introduction]({{< ref "#organization-api" >}}) for an explanation.
Action | Scope
--- | --- |
org.users:add | users:*
| Action | Scope |
| ------------- | -------- |
| org.users:add | users:\* |
**Example Request**:
@ -522,9 +526,9 @@ Only works with Basic Authentication (username and password), see [introduction]
See note in the [introduction]({{< ref "#organization-api" >}}) for an explanation.
Action | Scope
--- | --- |
org.users.role:update | users:*
| Action | Scope |
| --------------------- | -------- |
| org.users.role:update | users:\* |
**Example Request**:
@ -557,9 +561,9 @@ Only works with Basic Authentication (username and password), see [introduction]
See note in the [introduction]({{< ref "#organization-api" >}}) for an explanation.
Action | Scope
--- | --- |
org.users:remove | users:*
| Action | Scope |
| ---------------- | -------- |
| org.users:remove | users:\* |
**Example Request**:

1
docs/sources/http_api/other.md
View File

@ -5,7 +5,6 @@ keywords = ["grafana", "http", "documentation", "api", "other"]
aliases = ["/docs/grafana/latest/http_api/other/"]
+++
# Frontend Settings API
## Get Settings

8
docs/sources/http_api/playlist.md
View File

@ -21,12 +21,12 @@ Accept: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
```
Querystring Parameters:
Querystring Parameters:
These parameters are used as 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.
- **query** - Limit response to playlist having a name like this value.
- **limit** - Limit response to _X_ number of playlist.
**Example Response**:

8
docs/sources/http_api/preferences.md
View File

@ -9,9 +9,9 @@ aliases = ["/docs/grafana/latest/http_api/preferences/"]
Keys:
- **theme** - One of: ``light``, ``dark``, or an empty string for the default theme
- **homeDashboardId** - The numerical ``:id`` of a favorited dashboard, default: ``0``
- **timezone** - One of: ``utc``, ``browser``, or an empty string for the default
- **theme** - One of: `light`, `dark`, or an empty string for the default theme
- **homeDashboardId** - The numerical `:id` of a favorited dashboard, default: `0`
- **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.
@ -114,4 +114,4 @@ HTTP/1.1 200
Content-Type: text/plain; charset=utf-8
{"message":"Preferences updated"}
```
```

36
docs/sources/http_api/reporting.md
View File

@ -12,8 +12,8 @@ This API allows you to interact programmatically with the [Reporting]({{< relref
> Reporting is only available in Grafana Enterprise. Read more about [Grafana Enterprise]({{< relref "../enterprise" >}}).
> If you have [Fine-grained access Control]({{< relref "../enterprise/access-control/_index.md" >}}) enabled, for some endpoints you would need to have relevant permissions.
Refer to specific resources to understand what permissions are required.
> Refer to specific resources to understand what permissions are required.
## Send a report
> Only available in Grafana Enterprise v7.0+.
@ -28,9 +28,9 @@ Generate and send a report. This API waits for the report to be generated before
See note in the [introduction]({{< ref "#reporting-api" >}}) for an explanation.
Action | Scope
--- | --- |
reports:send | n/a
| Action | Scope |
| ------------ | ----- |
| reports:send | n/a |
### Example request
@ -48,11 +48,11 @@ Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
| ------------------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 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
| 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
@ -66,11 +66,11 @@ Content-Length: 29
| 200 | Report was sent. |
| 400 | Bad request (invalid json, missing content-type, missing or invalid fields, etc.). |
| 401 | Authentication failed, refer to [Authentication API]({{< relref "../http_api/auth.md" >}}). |
403 | User is authenticated but is not authorized to generate the report.
404 | Report not found.
500 | Unexpected error or server misconfiguration. Refer to server logs for more details.
400 | Bad request (invalid json, missing content-type, missing or invalid fields, etc.).
401 | Authentication failed, refer to [Authentication API]({{< relref "../http_api/auth.md" >}}).
403 | User is authenticated but is not authorized to generate the report.
404 | Report not found.
500 | Unexpected error or server misconfiguration. Refer to server logs for more details.
| 403 | User is authenticated but is not authorized to generate the report. |
| 404 | Report not found. |
| 500 | Unexpected error or server misconfiguration. Refer to server logs for more details. |
| 400 | Bad request (invalid json, missing content-type, missing or invalid fields, etc.). |
| 401 | Authentication failed, refer to [Authentication API]({{< relref "../http_api/auth.md" >}}). |
| 403 | User is authenticated but is not authorized to generate the report. |
| 404 | Report not found. |
| 500 | Unexpected error or server misconfiguration. Refer to server logs for more details. |

6
docs/sources/http_api/team.md
View File

@ -360,9 +360,9 @@ Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
JSON Body Schema:
- **theme** - One of: ``light``, ``dark``, or an empty string for the default theme
- **homeDashboardId** - The numerical ``:id`` of a dashboard, default: ``0``
- **timezone** - One of: ``utc``, ``browser``, or an empty string for the default
- **theme** - One of: `light`, `dark`, or an empty string for the default theme
- **homeDashboardId** - The numerical `:id` of a dashboard, default: `0`
- **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.

48
docs/sources/http_api/user.md
View File

@ -8,8 +8,8 @@ aliases = ["/docs/grafana/latest/http_api/user/"]
# User API
> If you are running Grafana Enterprise and have [Fine-grained access control]({{< relref "../enterprise/access-control/_index.md" >}}) enabled, for some endpoints you would need to have relevant permissions.
Refer to specific resources to understand what permissions are required.
> Refer to specific resources to understand what permissions are required.
## Search Users
`GET /api/users?perpage=10&page=1`
@ -18,9 +18,9 @@ Refer to specific resources to understand what permissions are required.
See note in the [introduction]({{< ref "#user-api" >}}) for an explanation.
Action | Scope
--- | --- |
users:read | global:users:*
| Action | Scope |
| ---------- | --------------- |
| users:read | global:users:\* |
**Example Request**:
@ -73,9 +73,9 @@ Content-Type: application/json
Content-Type: application/json
{
```
## Get single user by Id
## Get single user by Id
`GET /api/users/:id`
#### Required permissions
@ -134,9 +134,9 @@ Content-Type: application/json
Content-Type: application/json
Authorization: Basic YWRtaW46YWRtaW4=
```
Requires basic authentication and that the authenticated user is a Grafana Admin.
**Example Response**:
Requires basic authentication and that the authenticated user is a Grafana Admin.
**Example Response**:
```http
@ -146,6 +146,7 @@ Accept: application/json
```
## User Update
`PUT /api/users/:id`
#### Required permissions
@ -179,9 +180,9 @@ Content-Type: application/json
## Get Organizations for user
`GET /api/users/:id/orgs`
#### Required permissions
#### Required permissions
See note in the [introduction]({{< ref "#user-api" >}}) for an explanation.
| Action | Scope |
@ -234,9 +235,9 @@ Content-Type: application/json
```http
HTTP/1.1 200
Content-Type: application/json
```
Content-Type: application/json
```
## User
@ -273,9 +274,9 @@ Content-Type: application/json
```http
PUT /api/user/password HTTP/1.1
PUT /api/user/password HTTP/1.1
Accept: application/json
Content-Type: application/json
Accept: application/json
Content-Type: application/json
Authorization: Basic YWRtaW46YWRtaW4=
```
@ -311,9 +312,9 @@ Content-Type: application/json
POST /api/users/7/using/2 HTTP/1.1
Authorization: Basic YWRtaW46YWRtaW4=
```
```
**Example Response**:
**Example Response**:
```http
HTTP/1.1 200
Content-Type: application/json
@ -344,7 +345,6 @@ Content-Type: application/json
```
## Organizations of the actual User
## Organizations of the actual User
`GET /api/user/orgs`