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.

v1 is intentionally narrow

v1 is read-heavy and integration-safe by design. 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.
• Limited 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.
• Webhooks for important state transitions on Findings, Evidence claims, Submission packages, and Assessments.

Capabilities not in v1: organization administration, member and role mutation, license operations, billing, key management, backup and restore, bulk destructive writes, cross-organization operations. These require deeper authorization design and stay inside the Novantra application UI for now.

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. v1 is curated. If your integration needs a resource outside the v1 contract, 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.