Skip to content

Report Widget API

The Report Widget API renders a saved AutoROICalc report as a widget for another website, portal, or application. Version 1 supports the report chart and returns either a ready-to-use iframe document or a versioned JSON payload.

Widget access is configured separately for each report and is disabled by default.

Choose an Access Mode

Mode Who can load the widget Recommended use
disabled Nobody Reports that should remain inside AutoROICalc
authenticated A trusted backend with a service token Server-rendered portals, WordPress plugins, and private integrations
public Anyone with the generated public URL Browser-safe iframe embeds on websites

Public means accessible by URL

A public widget does not require a viewer to sign in. Only enable public access when the calculated report data is safe for anyone who obtains the URL.

Configure a Widget in AutoROICalc

  1. Open the saved report.
  2. Open the report sharing menu and select API Widget.
  3. Choose an access mode.
  4. Select Save. When public access is enabled for the first time, AutoROICalc opens the chart configuration before generating the iframe.
  5. Choose the chart type, visible data sets, and their order.
  6. Copy the generated iframe code or public URL.

Select Generate chart widget again to create another iframe with different chart options. Chart choices are stored in each generated URL, not in the report, so one report can provide multiple independently configured widgets. The dialog also lets you preview a generated chart and rotate the report's public URL.

Embed a Public Chart

For public access, AutoROICalc generates an iframe similar to this:

<iframe
  src="https://api.autoroicalc.com/embed/v1/reports/PUBLIC_ID/widgets/chart?chartType=bar&amp;datasetIndexes=2%2C0"
  loading="lazy"
  style="width:100%;height:420px;border:0"
  title="AutoROICalc report chart">
</iframe>

Paste the iframe into the destination page. Each iframe load requests the report widget with calculated report data embedded directly in the returned document. The built-in Refresh button requests an immediate data refresh.

When the report uses advanced layout settings, the embedded chart also inherits its global background and text colors, line thickness and dash, grid color and styling, and legend and scale font settings.

Hovering a chart date matches the in-app report chart: the tooltip groups all visible data-set values for that date and a dashed vertical guide marks the active position.

You can adjust the iframe width and height to fit the destination layout. Keep the generated src URL unchanged.

Public endpoint

GET /embed/v1/reports/{public_id}/widgets/chart?chartType=bar&datasetIndexes=2,0

No access token or service token is needed for this endpoint.

chartType accepts line, bar, pie, or doughnut. datasetIndexes is optional; its comma-separated sequence both selects the report datasets and controls their rendering order. Omit it to render all datasets in their report order. Indexes refer to the report's current dataset positions, so regenerate snippets after adding, removing, or reordering report datasets.

Authenticated Backend Access

Use authenticated mode when a trusted backend should retrieve the widget without publishing a public URL.

GET /service_token/v1/reports/{report_id}/widgets/chart?chartType=bar&datasetIndexes=2,0
X-Service-Token: <service-token>
Accept: text/html

Example:

curl "https://api.autoroicalc.com/service_token/v1/reports/42/widgets/chart?chartType=bar&datasetIndexes=2,0" \
  -H "X-Service-Token: $AUTOROICALC_SERVICE_TOKEN" \
  -H "Accept: text/html" \
  --output report-widget.html

The report must use authenticated or public widget access. A report with widget access disabled returns 403.

Add refresh=true to bypass the short report-widget cache and calculate fresh report data.

Never expose a service token in browser code

The service-token endpoint is for backend-to-backend requests only. Do not place the service token in HTML, browser JavaScript, a WordPress page, a mobile bundle, or a public repository.

Request the JSON Payload

Send Accept: application/json to the authenticated endpoint when your backend or plugin wants to render the chart itself:

curl "https://api.autoroicalc.com/service_token/v1/reports/42/widgets/chart?chartType=bar&datasetIndexes=0" \
  -H "X-Service-Token: $AUTOROICALC_SERVICE_TOKEN" \
  -H "Accept: application/json"

The response is versioned so clients can validate the schema before rendering it:

{
  "schemaVersion": 1,
  "widget": {
    "type": "chart",
    "appearance": {
      "backgroundColor": "#ffffff",
      "textColor": "#000000",
      "line": {"thickness": 2, "dash": 0},
      "grid": {"color": "#cecece", "thickness": 1, "dash": 0},
      "legend": {"fontSize": 14, "color": "#666666"},
      "scales": {"fontSize": 12, "color": "#666666"}
    },
    "options": {
      "chartType": "bar",
      "filterDataSets": true,
      "filteredDataSetIndexes": [0],
      "adjustItemsOrder": false,
      "orderedDataSetIndexes": []
    }
  },
  "reportData": {
    "reportId": 42,
    "reportName": "Monthly revenue",
    "reportDesc": "Revenue by month",
    "reportChartDateRange": ["January", "February"],
    "reportChartDataSets": [
      {
        "label": "Revenue",
        "color": "#2776a7",
        "data": [1200, 1450]
      }
    ]
  },
  "generatedAt": "2026-09-29T12:00:00+00:00"
}

Clients should check schemaVersion and widget.type before using the payload.

Configure Access Through the API

The AutoROICalc UI is the simplest way to manage widget access. An authenticated account session can also use these endpoints:

GET  /report/config/{report_id}/widget-api
PUT  /report/config/{report_id}/widget-api
POST /report/config/{report_id}/widget-api/rotate
Authorization: Bearer <access-token>

Set the access mode with:

{
  "access": "public"
}

The settings response for a public report includes the public ID, URL, and ready-to-copy iframe:

{
  "reportId": 42,
  "access": "public",
  "publicId": "4a5d149f-6af3-4fbe-b7f3-b021a979774c",
  "embedPath": "/embed/v1/reports/4a5d149f-6af3-4fbe-b7f3-b021a979774c/widgets/chart",
  "embedUrl": "https://api.autoroicalc.com/embed/v1/reports/4a5d149f-6af3-4fbe-b7f3-b021a979774c/widgets/chart",
  "embedHtml": "<iframe ...></iframe>"
}

Moving away from public immediately revokes the public URL. Enabling public access again creates a new URL.

Widget rendering options are never saved by these settings endpoints. Add them to each public or service-token widget request instead.

Rotate or Revoke a Public URL

Rotate a URL if it was shared with the wrong audience or may have been exposed. Rotation immediately invalidates the previous URL.

After rotation:

  1. Copy the new iframe code.
  2. Replace the old snippet everywhere it was embedded.
  3. Confirm the old URL no longer loads the widget.

To revoke public access without replacing it, change the report to authenticated or disabled.

Response Statuses

Status Meaning
200 Widget or settings returned successfully
400 Unsupported access mode, chart type, or dataset selection
401 Missing or invalid account access token on a settings endpoint
403 Invalid service token, or widget access is disabled for authenticated access
404 Report or public widget was not found
409 Public URL rotation was requested while public access was not enabled
429 Too many public widget requests
503 The chart runtime is temporarily unavailable

Current Scope

Version 1 renders the report's chart widget. Additional widget types can be added in later API versions without changing existing chart embed URLs.

Report Designer Widgets Report Sharing Service Token API