API quick start

IntensiveReports has two ways for other software to read its reports:

The report API (/ir-api/v1) is a REST API for scripts, dashboards, ticketing tools and monitoring. It returns JSON.
The MCP server (/ir-mcp) is for AI assistants. The assistant finds the right report for a question and reads it. See MCP server.

Both return exactly what the report shows in the app: the same rows, summary tiles (metrics), charts and notes. Both use the same clients, tokens and permissions, and every call is written to an audit log.

Before you start

An IntensiveReports administrator has to do two things first (see API and MCP access):

Switch the API on in Settings > API access. It is off by default, and while it is off every API address answers 404.
Create a client for you, for example “Monitoring script”. The administrator chooses which product areas the client may read and gets a token for it.

The token looks like ir1.<client id>.<secret>. It is shown only once, when the client is created. IntensiveReports keeps only a hash of it, so a lost token can’t be shown again. The administrator issues a new one instead. Treat it like a password.

The examples below use https://reports.example.com for your IntensiveReports address. Keep the token in an environment variable rather than in the script:

$env:IR_TOKEN = 'ir1.xxxx.xxxx'   # PowerShell

export IR_TOKEN='ir1.xxxx.xxxx'   # bash

Your first call

Every report has a fixed id, such as entra.users.guests. The report reference shows the id on each report’s page, and GET /ir-api/v1/reports lists every report your client may read.

With curl:

curl -H "Authorization: Bearer $IR_TOKEN" \
  "https://reports.example.com/ir-api/v1/reports/entra.users.guests?size=100"

With PowerShell:

$base    = 'https://reports.example.com/ir-api/v1'
$headers = @{ Authorization = "Bearer $env:IR_TOKEN" }

$report = Invoke-RestMethod "$base/reports/entra.users.guests?size=100" -Headers $headers
$report.state        # Ok
$report.loadedUtc    # when the data was read from Microsoft 365
$report.rows | Format-Table

Reading the answer

A report answer looks like this (shortened):

{
  "id": "entra.users.guests",
  "state": "Ok",
  "error": "",
  "partialWarning": "",
  "notApplicableReason": "",
  "loadedUtc": "2026-10-29T10:46:13+00:00",
  "isRunning": false,
  "progress": "",
  "metrics": [],
  "charts": [],
  "notes": [],
  "totalRows": 4,
  "filteredRows": 4,
  "page": 1,
  "size": 100,
  "filters": [],
  "rows": [
    {
      "DisplayName": "Anna (Fabrikam)",
      "UserPrincipalName": "anna_fabrikam.com#EXT#@example.onmicrosoft.com",
      "AccountEnabled": true,
      "CreatedDateTime": "2026-10-15T18:10:36+00:00"
    }
  ]
}

Field	What it tells you
`state`	Whether there is data: `Ok`, `Empty`, `Loading`, `NotLoaded`, `Failed`, `NotApplicable` or `SwitchedOff`. See states.
`loadedUtc`	When the data was read from Microsoft 365 (UTC). Use it to judge how fresh the answer is.
`metrics`	The report’s summary tiles, for example Admins without MFA = 4. Often all you need.
`notes`, `partialWarning`, `error`	Remarks on the data, a warning that part of it is missing, or why loading failed.
`totalRows`, `filteredRows`	Rows in the report, and rows left after your filters.
`rows`	One page of rows. The keys are the report’s column keys, listed on its page in the report reference.

Empty dates are null, never 0001-01-01.

Next steps

Authentication: tokens, certificates and Entra ID sign-in.
Using the API: reports that are still loading, paging, filters, refresh and scans, errors and limits.
MCP server: connect an AI assistant.
Examples: PowerShell, Python, Excel and Power BI, and turning findings into tickets.
REST API reference: every endpoint and field.