Exceptions

The Exceptions endpoints expose the exception register: every formally approved departure from your organization’s standard governance posture.

This is a read-only surface in v1. Creating, approving, and revoking exceptions happens in the Novantra UI (see the Exceptions user guide).

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

Scope required

Endpoints

List exceptions

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

Query parameters:

Response:

{
  "exceptions": [
    {
      "id": "excp_01HXY...",
      "exceptionKey": "property-A-service-route-separation-waiver",
      "title": "Service route separation waiver for Property A (historic building)",
      "exceptionKind": "compensating-control",
      "status": "active",
      "subjectModuleKey": "controls",
      "subjectResourceType": "control",
      "subjectResourceId": "ctrl_01HXY...",
      "subjectVersionId": null,
      "approverResponsibilityAssignmentId": "ra_01HXY...",
      "validFrom": "2026-01-01T00:00:00.000Z",
      "validUntil": "2031-01-01T00:00:00.000Z",
      "reviewDueAt": "2027-01-01T00:00:00.000Z",
      "createdAt": "2025-12-15T08:21:43.000Z",
      "updatedAt": "2025-12-20T11:42:33.000Z"
    }
  ],
  "pagination": {}
}

Get one exception

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

Path parameters:

Response: the single-exception shape from the list above.

Field notes

exceptionKind

Free text describing the kind: waiver, deviation, compensating-control, customized-approach, temporary-exception, risk-based-acceptance, or any other label your organization uses.

subjectModuleKey, subjectResourceType, subjectResourceId, subjectVersionId

The governed object the exception applies to. Typically a control, an obligation, a policy, an asset, or a process. See Attaching records to governed subjects.

approverResponsibilityAssignmentId

Points at the responsibility assignment naming who approved the exception. The responsibility record itself is not a v1 endpoint.

Justification and compensating-position

In the in-product UI, exceptions carry a justification (encrypted free text) and an optional compensating-position describing how a compensating control provides equivalent assurance. In v1 these snapshot fields are not exposed in the API; reads return the durable record fields.

Real-case integration: a risk dashboard surfaces expiring exceptions

A risk dashboard inside a customer’s BI tool wants to surface “exceptions expiring this quarter” as a board-level metric. The dashboard pulls from the Exceptions endpoints alongside other governance data.

The integration:

1. Calls GET /api/v1/governance/exceptions?status=active to pull the active register.
2. Filters in-warehouse for validUntil within the configured horizon (e.g., 90 days).
3. Joins approver IDs against the workspace’s responsibility-assignment list (separately maintained).
4. Renders a dashboard cell: count of expiring exceptions, by kind, with deep links back to the Novantra workspace for each.

The service account holds exactly governance.exceptions:read (plus the same responsibility-assignments:read cache used by other dashboard widgets). The integration pulls daily; the underlying register changes slowly so freshness is generous. Cursor pagination handles large registers cleanly.

A related pattern: a quarterly export of all exceptions approved in the previous quarter, for the audit committee. Same endpoint, different filter, different cadence.

Related

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