REST API

Novantra exposes a public REST API at /api/v1/... for integrators who need to ingest data into your workspace from external systems, export records into your own warehouse or GRC tooling, build custom integrations, or wire automation into your governance program.

The API is a deliberate product surface. It is curated, versioned, scope-token authenticated, server-side rate-limited, audited, and tenant-isolated. It is not a re-export of Novantra’s internal application routes.

Where to start

• v1 conventions - the contract every endpoint follows: base URL, request and response shapes, IDs, governed reason field on mutations, common patterns.
• Authentication - service accounts, OAuth client credentials, scopes.
• Workspace profile - confirm the workspace resolved from the current service-account token.
• Versioning - the /api/v1 contract, deprecation policy, what’s stable vs evolving.
• Errors - error envelope, status codes, idempotency keys for writes.
• Rate limits
• Pagination
• Webhooks - outbound notifications for finding events, evidence events, submission events, and assessment events.
• Governance reference - per-resource endpoint reference for the v1 surface.
• Changelog - additions, deprecations, and notes per release.

What the API covers

The API is read-heavy and integration-safe. It covers the resources customers most often need to pull into a warehouse, push from a scanner, or wire into a SIEM:

• Reads for Controls, Risks, Evidence claims and requirements, Assessments, Findings, Exceptions, Monitoring runs, Indicators, Submissions, Frameworks, Assets, Party Engagements, Change Management, and Vulnerability Management.
• Writes for the workflows where an external system is the natural source: creating Findings from scanners, creating Evidence claims with attachments, submitting Submission package events, and importing governed source updates.
• Webhooks for important state transitions on Findings, Evidence claims, Submission packages, and Assessments.

Administrative operations - organization administration, member and role management, license operations, billing, key management, and backup and restore - are performed in the Novantra application.

Why versioned

/api/v1/... lets us evolve and add capabilities without breaking your integration. When a future v2 or v1.x revision changes a shape, you keep your existing integration running against v1 until you choose to migrate. See Versioning for the deprecation policy.

What this is not

A short list to set expectations:

• Not the internal app routes. Novantra’s cloud and on-prem applications use private application routes that serve the web UI directly. Those are not stable, not authenticated for external callers, not documented for integration use, and may change without notice. Build against /api/v1/... only.
• Not a full data dump endpoint. The API exposes a curated set of resources. If your integration needs a resource the API does not currently expose, talk to your account team.
• Not a way to bypass workspace permissions. Scoped tokens enforce server-side authorization that mirrors the in-app permission model. A token can never see or change more than the human service-account owner can.