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.

Lynx API Guides

API Reference

Prerequisites

Base URL

Authentication

Available endpoints

List widgets for a screen

Retrieve widget data

Typical integration flow

Error handling

Permissions

​Prerequisites

​Base URL

​Authentication

​Available endpoints

List widgets for a screen

Retrieve widget data

​Typical integration flow

​Error handling

​Permissions

Prerequisites

Base URL

Authentication

Available endpoints

Typical integration flow

Error handling

Permissions