Skip to main content

Dashboards

Explore the API
Launch the OpenAPI Explorer to browse the live REST specs, inspect request and response schemas, and execute calls against your environment with an API key.

Dashboard endpoints let you hydrate the backend dashboard UI, customize layouts, and introspect widget availability per user or role.

export BASE_URL="http://localhost:3000/api"
export API_KEY="<paste your API key secret here>"
export WIDGET_ID="<dashboard item uuid>"
export ROLE_ID="<role uuid>"
export USER_ID="<user uuid>"

Mint an API key with dashboard features as described in Managing API keys before running these requests.

Fetch Layout — GET /dashboards/layout​

Feature: dashboard.widgets.view

curl -X GET "$BASE_URL/dashboards/layout" \
  -H "X-Api-Key: $API_KEY" \
  -H "Accept: application/json"

Response (trimmed):

{
  "widgets": [
    {
      "id": "8f221a66-08c3-4ef8-92af-dfb5eca80a2f",
      "definitionId": "core.stats.summary",
      "grid": { "x": 0, "y": 0, "w": 4, "h": 3 },
      "config": { "range": "30d" }
    }
  ]
}

Update Layout — PUT /dashboards/layout​

Feature: dashboard.widgets.manage

curl -X PUT "$BASE_URL/dashboards/layout" \
  -H "X-Api-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "widgets": [
      {
        "id": "8f221a66-08c3-4ef8-92af-dfb5eca80a2f",
        "definitionId": "core.stats.summary",
        "grid": { "x": 0, "y": 0, "w": 6, "h": 4 },
        "config": { "range": "90d" }
      }
    ]
  }'

Response:

{ "ok": true }

Retrieve Widget — GET /dashboards/layout/{itemId}​

Feature: dashboard.widgets.view

curl -X GET "$BASE_URL/dashboards/layout/$WIDGET_ID" \
  -H "X-Api-Key: $API_KEY" \
  -H "Accept: application/json"

Response:

{
  "id": "8f221a66-08c3-4ef8-92af-dfb5eca80a2f",
  "definitionId": "core.stats.summary",
  "grid": { "x": 0, "y": 0, "w": 6, "h": 4 },
  "config": { "range": "90d" }
}

Delete Widget — DELETE /dashboards/layout/{itemId}​

Feature: dashboard.widgets.manage

curl -X DELETE "$BASE_URL/dashboards/layout/$WIDGET_ID" \
  -H "X-Api-Key: $API_KEY" \
  -H "Accept: application/json"

Response:

{ "ok": true }

Role Widgets — GET /dashboards/roles/widgets​

Feature: dashboard.widgets.view
Use this endpoint to preview which widgets a role will expose.

curl -X GET "$BASE_URL/dashboards/roles/widgets?roleId=$ROLE_ID" \
  -H "X-Api-Key: $API_KEY" \
  -H "Accept: application/json"

Sample response:

{
  "items": [
    {
      "definitionId": "core.stats.summary",
      "title": "Summary",
      "description": "Key metrics for the tenant"
    }
  ]
}

User Widgets — GET /dashboards/users/widgets​

Feature: dashboard.widgets.view

curl -X GET "$BASE_URL/dashboards/users/widgets?userId=$USER_ID" \
  -H "X-Api-Key: $API_KEY" \
  -H "Accept: application/json"

Response mirrors the role endpoint but reflects direct user overrides. Combine both responses to build a complete widget catalog for custom dashboards.