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, creating new claims, and attaching controlled evidence files 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`
Read attachment metadata + open attachments	`governance.evidence:read`
Create claim + upload attachments	`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": "ger_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": {
    "nextCursor": null
  }
}

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: `submitted`, `accepted`, `rejected`, `expired`.

Response:


{
  "claims": [
    {
      "id": "gec_01HXY...",
      "evidenceRequirementId": "ger_01HXY...",
      "claimKey": "board-minutes-2026-q2",
      "title": "Q2 2026 board governance minutes",
      "status": "accepted",
      "subjectModuleKey": "governed-management-systems",
      "subjectResourceType": "management_system",
      "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": {
    "nextCursor": null
  }
}

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": "ger_01HXY...",
  "claimKey": "pentest-report-2026-04",
  "title": "Annual penetration test report, April 2026",
  "subjectModuleKey": "governed-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: "submitted" 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.

Create an attachment upload intent


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


{
  "claimId": "gec_01HXY...",
  "originalFilename": "pentest-report.pdf",
  "contentType": "application/pdf",
  "byteSize": 1048576,
  "checksumSha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "reason": "Attach the external penetration test report PDF to the evidence claim."
}

Response:


{
  "intent": {
    "id": "aui_01HXY...",
    "claimId": "gec_01HXY...",
    "originalFilename": "pentest-report.pdf",
    "contentType": "application/pdf",
    "byteSize": 1048576,
    "checksumSha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
    "status": "pending",
    "expiresAt": "2026-05-21T08:15:00.000Z",
    "createdAt": "2026-05-21T08:00:00.000Z"
  },
  "upload": {
    "transport": "multipart_server",
    "method": "POST",
    "path": "/api/v1/governance/evidence/attachments/upload-binary?claimId=gec_01HXY...&intentId=aui_01HXY...",
    "fieldName": "file"
  }
}

The server decides where and how the file is stored and binds it to the claim. Do not send storage bindings, buckets, object keys, object paths, or internal attachment-routing fields.

Upload the attachment binary


POST /api/v1/governance/evidence/attachments/upload-binary?claimId=gec_01HXY...&intentId=aui_01HXY...
Authorization: Bearer <access-token>
Content-Type: multipart/form-data
Idempotency-Key: external-system-batch-2026-05-21-item-42-binary

Send one multipart field named file. The filename, content type, byte size, and checksum must match the upload intent.

Response:


{
  "attachment": {
    "linkId": "arl_01HXY...",
    "artifactId": "art_01HXY...",
    "claimId": "gec_01HXY...",
    "originalFilename": "pentest-report.pdf",
    "contentType": "application/pdf",
    "byteSize": 1048576,
    "checksumSha256": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
    "status": "active",
    "createdAt": "2026-05-21T08:00:00.000Z"
  }
}

List attachment metadata


GET /api/v1/governance/evidence/attachments?claimId=gec_01HXY...
Authorization: Bearer <access-token>

Response:


{
  "attachments": [
    {
      "linkId": "arl_01HXY...",
      "artifactId": "art_01HXY...",
      "claimId": "gec_01HXY...",
      "originalFilename": "pentest-report.pdf",
      "contentType": "application/pdf",
      "byteSize": 1048576,
      "checksumSha256": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
      "status": "active",
      "createdAt": "2026-05-21T08:00:00.000Z"
    }
  ],
  "pagination": {
    "nextCursor": null
  }
}

Open attachment content


GET /api/v1/governance/evidence/attachments/open?claimId=gec_01HXY...&artifactId=art_01HXY...
Authorization: Bearer <access-token>

Response:


{
  "attachment": {
    "linkId": "arl_01HXY...",
    "artifactId": "art_01HXY...",
    "claimId": "gec_01HXY...",
    "originalFilename": "pentest-report.pdf",
    "contentType": "application/pdf",
    "byteSize": 1048576,
    "checksumSha256": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
    "status": "active",
    "createdAt": "2026-05-21T08:00:00.000Z"
  },
  "content": {
    "dataBase64": "<base64-file-content>",
    "inlinePreviewAllowed": true
  }
}

Use artifactId from the attachment metadata list. The response contains file bytes as base64; it does not return storage URLs or object locations.

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.
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, then use the attachment upload flow for the binary proof file.

`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 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.
- Idempotency-Key = the assessor’s reference number (guaranteed unique).
The service creates an attachment upload intent for the PDF and uploads the binary through the returned public upload path.
The claim lands as submitted with the attachment available for review. The security team reviewer is notified through the in-product workflow and accepts or rejects 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.

Evidence

Scopes required

Endpoints

List evidence requirements

List evidence claims

Create an evidence claim

Create an attachment upload intent

Upload the attachment binary

List attachment metadata

Open attachment content

Field notes

evidenceRequirementId

subjectModuleKey, subjectResourceType, subjectResourceId, subjectVersionId

sourceModuleKey, sourceResourceType, sourceResourceId, sourceVersionId

reason

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

Related

`evidenceRequirementId`

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

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

`reason`