Evidence

The Evidence endpoints expose two things: the evidence requirements your organization has defined (what proof needs to be collected) and the evidence claims that have been logged against those requirements (the actual proof, with validity and review state).

v1 supports reading both, and creating new claims so an external system (a security scanner, a backup system, a configuration management tool, a third-party report drop) can push evidence into the workspace directly.

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

Scopes required

Endpoint	Scope
Read requirements + read claims	`governance.evidence:read`
Create claim	`governance.evidence:write`

Endpoints

List evidence requirements


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

Query parameters:

Parameter	Type	Notes
`status`	string	Optional. Filter by status: `draft`, `active`, `retired`.

Response:


{
  "requirements": [
    {
      "id": "evreq_01HXY...",
      "requirementKey": "governance-board-minutes",
      "title": "Quarterly governance board minutes",
      "description": "Signed board minutes covering governance topics for the quarter.",
      "status": "active",
      "subjectModuleKey": null,
      "subjectResourceType": null,
      "createdAt": "2026-04-15T08:21:43.000Z",
      "updatedAt": "2026-04-15T08:21:43.000Z"
    }
  ],
  "pagination": {}
}

Get one evidence requirement


GET /api/v1/governance/evidence/requirements/:requirementId
Authorization: Bearer <access-token>

Returns the single-requirement shape from the list above.

List evidence claims


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

Query parameters:

Parameter	Type	Notes
`evidenceRequirementId`	string	Optional. Filter to claims against one requirement.
`status`	string	Optional. Filter by claim status.

Response:


{
  "claims": [
    {
      "id": "evclm_01HXY...",
      "evidenceRequirementId": "evreq_01HXY...",
      "claimKey": "board-minutes-2026-q2",
      "title": "Q2 2026 board governance minutes",
      "status": "approved",
      "subjectModuleKey": "management-systems",
      "subjectResourceType": "managementSystem",
      "subjectResourceId": "gms_01HXY...",
      "subjectVersionId": null,
      "sourceModuleKey": "dms",
      "sourceResourceType": "document",
      "sourceResourceId": "doc_01HXY...",
      "sourceVersionId": "docv_01HXY...",
      "validFrom": "2026-04-15T00:00:00.000Z",
      "validUntil": "2026-07-15T00:00:00.000Z",
      "createdAt": "2026-04-17T10:21:43.000Z",
      "updatedAt": "2026-04-20T11:42:33.000Z"
    }
  ],
  "pagination": {}
}

Get one evidence claim


GET /api/v1/governance/evidence/claims/:claimId
Authorization: Bearer <access-token>

Returns the single-claim shape from the list above.

Create an evidence claim


POST /api/v1/governance/evidence/claims
Authorization: Bearer <access-token>
Content-Type: application/json
Idempotency-Key: external-system-batch-2026-05-21-item-42


{
  "evidenceRequirementId": "evreq_01HXY...",
  "claimKey": "pentest-report-2026-04",
  "title": "Annual penetration test report, April 2026",
  "subjectModuleKey": "controls",
  "subjectResourceType": "control",
  "subjectResourceId": "ctrl_01HXY...",
  "sourceModuleKey": "external",
  "sourceResourceType": "report",
  "sourceResourceId": "REF-2026-PT-038",
  "sourceSnapshot": {
    "assessor": "Independent assessor reference REF-2026-PT-038",
    "engagementDate": "2026-04-17",
    "reportTitle": "External infrastructure penetration test report"
  },
  "claimSnapshot": {
    "submittedBy": "security-analyst@example.com",
    "summary": "No critical findings. Three high-severity findings under remediation."
  },
  "reason": "External penetration test result, automated ingest from secure file drop."
}

Response: the created claim record, with status: "draft" by default. The claim is then routed for human review through the in-product workflow.

Use idempotency keys for every create call. A claim is high-cost to deduplicate manually if your integration retries; pair every POST with a stable key. See Errors for idempotency semantics.

Field notes

`evidenceRequirementId`

Optional but recommended. When set, the claim is tied to one of the requirements you’ve defined, and the in-product UI groups it under that requirement for reviewers. Standalone claims (no requirement) are accepted but harder to reason about during an audit.

`subjectModuleKey`, `subjectResourceType`, `subjectResourceId`, `subjectVersionId`

The governed object this claim is about. Typically a control, an obligation, or a management system. See Attaching records to governed subjects.

`sourceModuleKey`, `sourceResourceType`, `sourceResourceId`, `sourceVersionId`

Where the proof came from. Typical sources:

dms + document for documents in the workspace document management.
forms + response for completed form responses.
artifacts + artifact for direct artifact uploads.
external + a kind you choose (report, attestation, log-export, etc.) for proof originating outside the workspace.

When source is external, capture identifying detail in the sourceSnapshot so an auditor can trace the proof back to its origin.

`validFrom` and `validUntil`

The claim’s validity window. Reviewers expect this; the in-product UI surfaces expiry warnings. If your integration knows the validity window (most do: the proof itself has a date), include it. If not, leave them null and the in-product reviewer will set them.

`reason`

Required, like every mutation. Explain the source and intent of the claim. Auditors may review your reason text; make it meaningful.

Real-case integration: an external assessor drops penetration test reports

A security consultancy delivers annual penetration test reports to its enterprise customers through a secure file drop. The reports include a structured summary file plus the full PDF.

The customer wants reports to land in Novantra automatically and be routed for internal review without manual upload. Their integration runs as a small service that watches the drop directory.

When a new report arrives:

The service uploads the PDF as an artifact through the in-product artifact upload flow (separate API; not covered in this page).
The service then calls POST /api/v1/governance/evidence/claims with:
- evidenceRequirementId pointing at the annual-penetration-test requirement.
- subjectResourceId pointing at the control the test was scoped against.
- sourceModuleKey: "external" and the assessor’s reference number.
- sourceSnapshot capturing assessor name, engagement date, report scope.
- claimSnapshot capturing the high-level findings summary.
- validFrom = engagement completion date, validUntil = one year later.
- Idempotency-Key = the assessor’s reference number (guaranteed unique).
The claim lands as draft. The security team reviewer is notified through the in-product workflow and approves it.

The integration uses a service account with governance.evidence:write scope and nothing else. It respects rate limits and retries with the same idempotency key on transient failures. A repeated drop of the same report (the assessor occasionally re-sends) does not create duplicate claims because the idempotency key matches.

This pattern works for any external evidence source: backup completion reports, configuration baseline exports, training completion exports, third-party attestations.

Evidence user guide - what the evidence module does and when to reach for it.
v1 conventions - shared request and response patterns.
Authentication - service accounts and scopes.
Errors - idempotency keys and retry guidance.
Webhooks - subscribe to evidence.claim.created, evidence.claim.approved, evidence.claim.rejected.