Skip to main content
POST
Add a widget to a report page

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Headers

X-API-Key
string | null

Path Parameters

project_id
string<uuid>
required
report_id
string<uuid>
required
page_id
string<uuid>
required

Body

application/json

Request body for adding a new widget to a report page.

widget_type
string
required

Type of widget to render. One of: stat_card, line_chart, bar_chart, donut_chart, table, text.

title
string
required

Display title shown in the widget header.

Required string length: 1 - 255
data_source
string | null

Identifier for the data source powering this widget (e.g., 'ranking_overview', 'backlink_summary'). Null for static widgets such as 'text'.

config
Config · object

Widget-specific configuration object (metrics to display, chart colours, table columns, text content, etc.).

position_x
integer
default:0

Horizontal grid position (column index, 0-based).

position_y
integer
default:0

Vertical grid position (row index, 0-based).

width
integer
default:1

Width of the widget in grid columns (1–3).

Required range: 1 <= x <= 3
height
integer
default:1

Height of the widget in grid rows (1–2).

Required range: 1 <= x <= 2

Response

Successful Response

success
boolean
default:true
data
ReportWidgetResponse · object | null

A single report widget as returned by the API.