Skip to main content
The Widgets Dashboard APIs allow you to discover which widgets are available for a given screen and then fetch the data for each individual widget. The APIs are exposed by the Lynx Operational API and proxy requests to the internal Cortex Reports service.

​
Prerequisites

Before making calls to the Widget API, you need to have:

​
Base URL

https://<host>/v1/dashboard
If the server is configured with UseBasePath: true, all routes are prefixed with /operational:
https://<host>/operational/v1/dashboard

​
Authentication

All endpoints require authentication via JWT bearer token. Include the token in every request: 
Authorization: Bearer <token>
See Security & Token for details on obtaining a token.

​
Available Endpoints

The following endpoints are available. Select a card to view the full API reference.

List Widgets for a Screen

Returns all widgets configured for a given screen type, including their IDs, names, and configurations.

Retrieve Widget Data (POST)

Fetches data for a specific widget with full filter support (date range, machine ID, etc.). Recommended for most use cases.

Retrieve Widget Data (GET)

Simple variant for fetching widget data via query parameters. No filter support - use the POST variant when filters are needed.
The GET simple variant (GET /v1/dashboard/widget-data) is not included in the API reference as it is not defined in the OpenAPI spec. Use the POST variant for filter support and full API reference coverage.

​
Typical Integration Flow

A standard integration follows three steps: discover available widgets, fetch their data with optional filters, then parse the response payload. 
1. GET /v1/dashboard/widgets?screenTypeId=1
       → Discover available widgets and their widgetTypeId values

2. POST /v1/dashboard/get-widget-data  (recommended - supports filters)
   OR
   GET  /v1/dashboard/widget-data      (simple - no filter support)
       → Fetch widget data, optionally scoped by entity and filtered by date/machine

3. Parse the response:
   - widgetDetails.widgetConfig → rendering hints
   - data                       → actual data payload (structure varies per widget)

​
Error Handling

The following HTTP status codes may be returned by the widget endpoints:
HTTP StatusCause
400Missing required field, invalid parameter value
401Missing or expired bearer token
403Authenticated but missing the required permission key for this endpoint
500Backend error - common causes: wrong Content-Type header (use application/json), invalid widgetTypeId, or an unrecognized filter format

​
Permissions

Each endpoint requires the authenticated user to have a specific menu permission assigned in Lynx. Permissions are checked by the GetContext() middleware on every request:
EndpointPermission KeyOAuth Scope
GET /v1/dashboard/widgetslynx_report_get_widgetsreport:read
POST /v1/dashboard/get-widget-datalynx_report_get_widget_datareport:read
GET /v1/dashboard/widget-datalynx_report_get_widgetreport:read
GET /v1/dashboard/widget-data requires lynx_report_get_widget, which is separate from lynx_report_get_widget_data (the POST variant). If you have access to the POST endpoint but receive a 403 on the GET endpoint, request the lynx_report_get_widget permission in your Lynx role configuration.