Assessments

The Assessments endpoints expose the assessment register: every assessment your organization has run or is running, with its subject, methodology, result, and conclusion.

This is a read-only surface in v1. Creating, conducting, and closing assessments happens in the Novantra UI (see the Assessments user guide).

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

Scope required

Endpoints

List assessments

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

Query parameters:

Response:

{
  "assessments": [
    {
      "id": "asmt_01HXY...",
      "assessmentKey": "site-a-physical-access-quarterly-2026-q2",
      "title": "Site A physical access quarterly self-assessment",
      "description": "Q2 2026 quarterly self-assessment of physical access controls at Site A.",
      "status": "completed",
      "subjectModuleKey": "controls",
      "subjectResourceType": "control",
      "subjectResourceId": "ctrl_01HXY...",
      "subjectVersionId": null,
      "assessorResponsibilityAssignmentId": "ra_01HXY...",
      "reviewerResponsibilityAssignmentId": "ra_01HXZ...",
      "createdAt": "2026-04-15T08:21:43.000Z",
      "updatedAt": "2026-05-25T14:08:33.000Z",
      "completedAt": "2026-05-25T14:08:33.000Z"
    }
  ],
  "pagination": {}
}

Get one assessment

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

Path parameters:

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

Field notes

Methodology and results

In the in-product UI, an assessment carries rich detail: methodology snapshot, question/response set, test procedures, samples, sample results, scoring against an evaluation model, and conclusions. In v1 these structured snapshots are not exposed in the API surface; reads return the durable record (id, subject, assessor, reviewer, status, completion time). The full evaluation detail is available through the in-product UI.

subjectModuleKey, subjectResourceType, subjectResourceId, subjectVersionId

The governed object being assessed. Typically a control, but can be a risk, an obligation, an asset, a vendor engagement, a management system, or any other governed object. See Attaching records to governed subjects.

assessorResponsibilityAssignmentId and reviewerResponsibilityAssignmentId

Point at the responsibility assignments naming the assessor and reviewer. The responsibility records themselves are not v1 endpoints; the in-product UI shows the names and roles.

Real-case integration: feeding completed assessments into a continuous-monitoring dashboard

A platform reliability team operates a continuous-monitoring dashboard that combines security telemetry, incident counts, and the most recent assessment result for each control they care about. They want the dashboard to show “control X was assessed on date Y, result Z” alongside the live signals.

The integration:

1. Calls GET /api/v1/governance/assessments?status=completed periodically (every few hours).
2. Joins each assessment’s subjectResourceId against the controls register (also via the v1 API).
3. Surfaces the latest completed assessment per control in the dashboard.
4. When the assessment’s updatedAt is older than the configured cadence (e.g., one quarter), the dashboard flags the control as “assessment overdue.”

The service account holds exactly governance.assessments:read and governance.controls:read. The integration uses cursor pagination to walk the assessments list and caches the result; per-control lookups against the cached register are fast.

The assessment.completed webhook lets this integration receive new assessments as they complete, instead of polling. The dashboard can subscribe and process the assessment result within seconds of completion.

Related

• Assessments user guide - what the assessments module does and when to reach for it.
• v1 conventions - shared request and response patterns.
• Webhooks - subscribe to assessment.completed.