Indicators

The Indicators endpoints expose indicator definitions (what is being measured, with target and thresholds) and indicator measurements (each value at a point in time).

This is a read-only surface in v1. Creating, updating, and retiring indicators happens in the Novantra UI (see the Indicators user guide).

For shared conventions (auth, errors, pagination, ID format), read v1 conventions first.

Scope required

Endpoint	Scope
All read endpoints below	`governance.indicators:read`

Endpoints

List indicator definitions


GET /api/v1/governance/indicators
Authorization: Bearer <access-token>

Query parameters:

Parameter	Type	Notes
`status`	string	Optional. Filter by status.
`indicatorKind`	string	Optional. Filter by kind: `kpi`, `kri`, `kci`, `kqi`, `maturity`, `custom`.

Response:


{
  "indicators": [
    {
      "id": "ind_01HXY...",
      "indicatorKey": "vendor-due-diligence-completion-rate",
      "title": "Vendor due-diligence completion rate",
      "indicatorKind": "kci",
      "status": "active",
      "subjectModuleKey": "controls",
      "subjectResourceType": "control",
      "subjectResourceId": "ctrl_01HXY...",
      "ownerResponsibilityAssignmentId": "ra_01HXY...",
      "createdAt": "2026-03-01T08:21:43.000Z",
      "updatedAt": "2026-05-25T14:08:33.000Z",
      "latestMeasurementValue": "94.5",
      "latestMeasurementAt": "2026-05-29T03:00:00.000Z"
    }
  ],
  "pagination": {}
}

Get one indicator definition


GET /api/v1/governance/indicators/:indicatorId
Authorization: Bearer <access-token>

Returns the single-definition shape from the list above.

List indicator measurements


GET /api/v1/governance/indicators/measurements
Authorization: Bearer <access-token>

Query parameters:

Parameter	Type	Notes
`indicatorDefinitionId`	string	Required. Filter to measurements for one indicator (mandatory because cross-indicator walks are expensive).
`since`	datetime	Optional. Filter to measurements at or after this time.

Response:


{
  "measurements": [
    {
      "id": "indm_01HXY...",
      "indicatorDefinitionId": "ind_01HXY...",
      "measurementValue": "94.5",
      "measurementAt": "2026-05-29T03:00:00.000Z",
      "createdAt": "2026-05-29T03:00:14.000Z"
    },
    {
      "id": "indm_01HXZ...",
      "indicatorDefinitionId": "ind_01HXY...",
      "measurementValue": "96.1",
      "measurementAt": "2026-05-22T03:00:00.000Z",
      "createdAt": "2026-05-22T03:00:14.000Z"
    }
  ],
  "pagination": {}
}

Field notes

`indicatorKind`

Free text. Common values are kpi, kri, kci, kqi, maturity, custom.

`latestMeasurementValue` and `latestMeasurementAt`

Convenience fields on the definition that surface the most recent measurement without requiring a follow-up call. Useful for dashboards that want a quick “current value” without walking the full measurement history.

`subjectModuleKey`, `subjectResourceType`, `subjectResourceId`

The governed object the indicator is about. See Attaching records to governed subjects.

Target, threshold, breach policy

In the in-product UI, indicators carry rich definitions including target, tolerance, warning and breach thresholds, trend policy, and breach policy. In v1 these structured snapshots are not exposed in the API surface; reads return the durable identifying fields plus the latest measurement convenience. Full configuration lives in the in-product UI.

`measurementValue`

A string in API responses to preserve numeric precision (some indicators carry percentages with decimal points, others carry counts, others carry maturity-level strings). Parse appropriately on your side.

Real-case integration: surfacing the scorecard in a leadership dashboard

A leadership team uses an external BI tool for its monthly business review. The audit and risk leads want governance indicators alongside business metrics: KCIs for control effectiveness, KRIs for risk posture, KPIs for governance program performance.

The integration:

Calls GET /api/v1/governance/indicators to pull the definition list and the latest measurement on each.
For indicators where the leadership team wants the trend chart, calls GET /api/v1/governance/indicators/measurements?indicatorDefinitionId=<id>&since=<six-months-ago> to pull the recent measurement history.
Renders the indicators in the BI tool’s standard widgets: number tiles for current values, sparklines for trends, status bars for warning vs breach.
Hyperlinks each indicator back to the Novantra workspace so a reader can drill in.

The service account holds exactly governance.indicators:read. The integration runs weekly (with on-demand refresh available); the underlying measurement cadence varies per indicator but most are daily or weekly. Cursor pagination handles indicators with long histories.

A common pattern: a “governance index” widget that combines several indicators into a single composite score, weighted by importance. The composite computation happens in the BI tool; Novantra exposes the underlying measurements.

Indicators user guide - what the indicators module does and when to reach for it.
v1 conventions - shared request and response patterns.
Authentication - service accounts and scopes.