REST API

What it is

The REST API exposes the same records you see in the app, controls, evidence, risks, vendors, policies, personnel, and the privacy data map, as JSON over HTTPS. It is the right choice for scripts, CI pipelines, and anything that needs to upload a file; AI clients should use the MCP server instead.

Base URL and reference

The public paths above are rate-limited to 60 requests per minute per IP.

Authentication

Every /v1 and /v2 request needs an Authorization: Bearer header. Two credentials are accepted:

A missing, malformed, expired, or revoked credential returns 401 with a WWW-Authenticate header and this body (the message says which check failed):

{ "error": { "code": "UNAUTHORIZED", "message": "..." } }

A valid credential that lacks the scope for a route returns 403:

{ "error": { "code": "FORBIDDEN", "message": "Insufficient permissions" } }

Resources

The exact operations, parameters, and schemas for each resource are in the OpenAPI document; this page only shows the shape they share.

Privacy data map ingestion

POST /v1/privacy/datamaps accepts a fideslang manifest (.fides/datamap.yml parsed to JSON) and materialises systems, datasets, and processing activities into the data map. It is idempotent on slug: re-pushing identical content is a no-op, a changed manifest creates a new immutable version, and anything the manifest no longer names is archived rather than deleted. It requires write:datamaps and the privacy segment. GET /v1/privacy/ropa/export returns the RoPA register as CSV with read:datamaps. AI inventory manifests have no REST route; push them through the MCP tool ingestAiInventory.

Example: list controls

GET /v1/controls returns the organization's controls, filterable by status, frameworkId, domain, ownerType, ownerRefId, and search. It needs read:controls.

curl -s "https://api.noru.tech/v1/controls?status=in_progress&limit=2" \
  -H "Authorization: Bearer $NORU_API_KEY"

const response = await fetch(
  "https://api.noru.tech/v1/controls?status=in_progress&limit=2",
  { headers: { Authorization: `Bearer ${process.env.NORU_API_KEY}` } },
);

if (!response.ok) {
  const { error } = await response.json();
  throw new Error(`${error.code}: ${error.message}`);
}

const { data, pagination } = await response.json();
console.log(pagination.total, "controls;", data.length, "in this page");

A trimmed response:

{
  "data": [
    {
      "id": "sm-01",
      "controlId": "SM-01",
      "name": "Information security policy",
      "status": "in_progress",
      "owner": { "type": "user", "refId": "user_123", "resolvedUserId": "user_123" }
    }
  ],
  "pagination": { "total": 87, "limit": 2, "offset": 0 }
}

GET /v1/controls/sm-01 returns one control. The lowercase id is the canonical identifier; the uppercase controlId is for display, and routes accept either.

Pagination and filters

Every list response wraps rows in data and reports total, limit, and offset under pagination. Page until offset + limit reaches total.

Errors

Every error uses the same envelope: an error object with a code and a human-readable message.

Rate limits

Authenticated /v1 and /v2 calls are limited to 500 requests per 10 minutes per credential, counted per API key or per OAuth token. Every response carries the current state:

Billing gate

/v1/evidence additionally requires the organization's billing to be active. When it is not, those routes answer 402 PAYMENT_REQUIRED until an admin resolves it under Settings›Billing or with the Noru team.

Activity and audit trail

Every authenticated request is recorded in the organization's activity log with source api, the action METHOD /path, and the API key (or OAuth user) as actor. The key's Last Used timestamp is updated at the same time. Writes made through the API are therefore visible in the same history as writes made in the app.

What the REST API does not do

• It never returns data from an organization other than the credential's.
• It does not create or delete controls; controls come from the frameworks you enable.
• File uploads happen only through POST /v1/evidence/upload as multipart/form-data, up to 50 MB. No other route accepts a file.
• It does not push AI inventory manifests (use MCP ingestAiInventory).
• It does not stream or send webhooks; poll, or use the activity log.

Related

• API keys
• MCP server
• Roles and permissions
• Statuses for every value a status filter accepts