Library Element API

    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

    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 or 2 for library variables.
    • 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 ID(s) 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:

    Example Response:

    1. HTTP/1.1 200
    2. Content-Type: application/json
    4. {
    5.   "result": {
    6.      "totalCount": 15,
    7.      "page": 1,
    8.      "perPage": 10
    9.      "elements": [
    10.         {
    11.             "id": 25,
    12.             "orgId": 1,
    13.             "folderId": 0,
    14.             "uid": "V--OrYHnz",
    15.             "name": "API docs Example",
    16.             "kind": 1,
    17.             "type": "text",
    18.             "description": "",
    19.             "model": {...},
    20.             "version": 1,
    21.             "meta": {
    22.                 "folderName": "General",
    23.                 "folderUid": "",
    24.                 "connectedDashboards": 1,
    25.                 "created": "2021-09-27T09:56:17+02:00",
    26.                 "updated": "2021-09-27T09:56:17+02:00",
    27.                 "createdBy": {
    28.                     "id": 1,
    29.                     "name": "admin",
    30.                     "avatarUrl": "/avatar/46d229b033af06a191ff2267bca9ae56"
    31.                 },
    32.                 "updatedBy": {
    33.                     "id": 1,
    34.                     "name": "admin",
    35.                     "avatarUrl": "/avatar/46d229b033af06a191ff2267bca9ae56"
    36.                 }
    37.             }
    38.         },
    39.         {...}
    40.         {...}
    41.      ],
    42.   }
    43. }

    Status Codes:

    • 200 – Found
    • 401 – Unauthorized

    GET /api/library-elements/:uid

    Returns a library element with the given UID.

    Example Request:

    1. GET /api/library-elements/V--OrYHnz HTTP/1.1
    2. Accept: application/json
    3. Content-Type: application/json
    4. Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk

    Example Response:

    1. HTTP/1.1 200
    2. Content-Type: application/json
    4. {
    5.     "result": {
    6.       "id": 25,
    7.       "orgId": 1,
    8.       "folderId": 0,
    9.       "uid": "V--OrYHnz",
    10.       "name": "API docs Example",
    11.       "kind": 1,
    12.       "type": "text",
    13.       "description": "",
    14.       "model": {...},
    15.       "version": 1,
    16.       "meta": {
    17.           "folderName": "General",
    18.           "folderUid": "",
    19.           "connectedDashboards": 1,
    20.           "created": "2021-09-27T09:56:17+02:00",
    21.           "updated": "2021-09-27T09:56:17+02:00",
    22.           "createdBy": {
    23.               "id": 1,
    24.               "name": "admin",
    26.           },
    27.           "updatedBy": {
    28.               "name": "admin",
    29.               "avatarUrl": "/avatar/46d229b033af06a191ff2267bca9ae56"
    30.           }
    31.       }
    32.    }
    33. }

    Status Codes:

    • 200 – Found
    • 401 – Unauthorized
    • 404 – Library element not found

    Get library element by name

    Returns a library element with the given name

    Example Request:

    Example Response:

    1. HTTP/1.1 200
    2. Content-Type: application/json
    4. {
    5.     "result": {
    6.       "id": 25,
    7.       "orgId": 1,
    8.       "folderId": 0,
    9.       "uid": "V--OrYHnz",
    10.       "name": "API docs Example",
    11.       "kind": 1,
    12.       "type": "text",
    13.       "description": "",
    14.       "model": {...},
    15.       "version": 1,
    16.       "meta": {
    17.           "folderName": "General",
    18.           "folderUid": "",
    19.           "connectedDashboards": 1,
    20.           "created": "2021-09-27T09:56:17+02:00",
    21.           "updated": "2021-09-27T09:56:17+02:00",
    22.           "createdBy": {
    23.               "id": 1,
    24.               "name": "admin",
    25.               "avatarUrl": "/avatar/46d229b033af06a191ff2267bca9ae56"
    26.           },
    27.           "updatedBy": {
    28.               "id": 1,
    29.               "name": "admin",
    30.               "avatarUrl": "/avatar/46d229b033af06a191ff2267bca9ae56"
    31.           }
    32.       }
    33.    }
    34. }

    Status Codes:

    • 200 – Found
    • 401 – Unauthorized
    • 404 – Library element not found

    GET /api/library-elements/:uid/connections

    Returns a list of connections for a library element based on the UID specified.

    Example Request:

    1. GET /api/library-elements/V--OrYHnz/connections HTTP/1.1
    2. Accept: application/json
    3. Content-Type: application/json
    4. Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk

    Example Response:

    1. HTTP/1.1 200
    2. Content-Type: application/json
    4. {
    5.     "result": [
    6.         {
    7.             "id": 148,
    8.             "kind": 1,
    9.             "elementId": 25,
    10.             "connectionId": 527,
    11.             "created": "2021-09-27T10:00:07+02:00",
    12.             "createdBy": {
    13.                 "id": 1,
    14.                 "name": "admin",
    15.                 "avatarUrl": "/avatar/46d229b033af06a191ff2267bca9ae56"
    16.             }
    17.         }
    18.     ]
    19. }

    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.
    • 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 or 2 for library variables.
    • uid – Optional, the unique identifier.

    Example Request:

    1. HTTP/1.1 200
    2. Content-Type: application/json
    4. {
    5.     "result": {
    6.         "id": 28,
    7.         "orgId": 1,
    8.         "folderId": 0,
    9.         "uid": "nErXDvCkzz",
    11.         "kind": 1,
    12.         "type": "",
    13.         "description": "",
    14.         "model": {...},
    15.         "version": 1,
    16.             "folderName": "General",
    17.             "folderUid": "",
    18.             "connectedDashboards": 0,
    19.             "created": "2021-09-30T09:14:22.378307+02:00",
    20.             "updated": "2021-09-30T09:14:22.378307+02:00",
    21.             "createdBy": {
    22.                 "id": 1,
    23.                 "name": "admin",
    24.                 "avatarUrl": "/avatar/46d229b033af06a191ff2267bca9ae56"
    25.             },
    26.             "updatedBy": {
    27.                 "id": 1,
    28.                 "name": "admin",
    29.                 "avatarUrl": "/avatar/46d229b033af06a191ff2267bca9ae56"
    30.             }
    31.         }
    32.     }
    33. }

    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

    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.
    • 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 or 2 for library variables.
    • version – Version of the library element you are updating.
    • uid – Optional, the unique identifier.

    Example Request:

    1. PATCH /api/library-elements/nErXDvCkzz HTTP/1.1
    2. Accept: application/json
    3. Content-Type: application/json
    4. Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
    6. {
    7.   "name": "Renamed library panel",
    8.   "kind": 1,
    9.   "version": 1
    10. }

    Example Response:

    1. HTTP/1.1 200
    2. Content-Type: application/json
    4. {
    5.     "result": {
    6.         "id": 28,
    7.         "orgId": 1,
    8.         "folderId": 0,
    9.         "uid": "nErXDvCkzz",
    10.         "name": "Renamed library panel",
    11.         "kind": 1,
    12.         "type": "",
    13.         "description": "",
    14.         "model": {
    15.             "description": "",
    16.             "type": ""
    17.         },
    18.         "version": 2,
    19.         "meta": {
    20.             "folderName": "General",
    21.             "folderUid": "",
    22.             "connectedDashboards": 0,
    23.             "created": "2021-09-30T09:14:22+02:00",
    24.             "updated": "2021-09-30T09:25:57.697214+02:00",
    25.             "createdBy": {
    26.                 "id": 1,
    27.                 "name": "admin",
    28.                 "avatarUrl": "/avatar/46d229b033af06a191ff2267bca9ae56"
    29.             },
    30.             "updatedBy": {
    31.                 "id": 1,
    32.                 "name": "admin",
    33.                 "avatarUrl": "/avatar/46d229b033af06a191ff2267bca9ae56"
    34.             }
    35.         }
    36.     }
    37. }

    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.

    Example Request:

    Example Response:

    1. HTTP/1.1 200
    2. Content-Type: application/json
    4. {
    5.     "message": "Library element deleted"

    Status Codes:

    • 200 – Deleted
    • 401 – Unauthorized
    • 400 – Bad request
    • 403 – Access denied
    • 404 – Library element not found