Get Machine Widget Data (API)

The Widgets Dashboard APIs let you discover which widgets are available for a given screen and fetch the data for each individual widget.

Prerequisites

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

• Access to the Lynx QA or Production environment
• A valid API token (See Security & Token)
• Machines or Operator IDs

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 <YOUR_ACCESS_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

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

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 Status	Cause
400	Missing required field, invalid parameter value
401	Missing or expired bearer token
403	Authenticated but missing the required permission key for this endpoint
500	Backend 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:

Endpoint	Permission Key	OAuth Scope
GET /v1/dashboard/widgets	lynx_report_get_widgets	report:read
POST /v1/dashboard/get-widget-data	lynx_report_get_widget_data	report:read
GET /v1/dashboard/widget-data	lynx_report_get_widget	report: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.