API Reference

The zGovern REST API lets you integrate compliance data into your own tools and workflows. All endpoints return JSON and require JWT authentication unless noted.

API Basics

Base URL http://localhost:4000/api (local)  /  https://app.zgovern.com/api (production)
Authentication Bearer JWT in the Authorization header
Content-Type application/json for all requests except file uploads (multipart/form-data)
Response format { "success": boolean, "message": string, "data": T }
HTTP status codes 200 OK, 201 Created, 400 Bad Request, 401 Unauthorized, 403 Forbidden, 404 Not Found, 500 Server Error

Authentication Header

Obtain a token via POST /api/auth/login, then include it in all subsequent requests:

Request header
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Error Format

Error response
{
  "success": false,
  "message": "Control not found",
  "data": null
}
ℹ
Frontend API pattern In the React frontend, use the api.get/post/patch/delete wrapper from src/lib/api.ts for JSON requests. For file uploads, use raw fetch() with multipart/form-data and a manual Authorization header.

Authentication

POST /api/auth/register Create a new user account
Request Body
{
  "firstName": "Jane",
  "lastName": "Smith",
  "email": "jane@acme.com",
  "password": "SecureP@ssw0rd!"
}
Response 201
{
  "success": true,
  "message": "Account created successfully",
  "data": { "token": "eyJhbG...", "user": { "id": "...", "email": "jane@acme.com", "role": "MEMBER" } }
}
POST /api/auth/login Authenticate and receive a JWT token
Request Body
{
  "email": "admin@zgovern.com",
  "password": "admin123!"
}
Response 200
{
  "success": true,
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJjbHh...",
    "user": {
      "id": "clxr8k2vp0001lg3a",
      "firstName": "Admin",
      "lastName": "User",
      "email": "admin@zgovern.com",
      "role": "ADMIN"
    }
  }
}
POST /api/auth/forgot-password Request a password reset email
Request Body
{ "email": "jane@acme.com" }
POST /api/auth/reset-password Reset password using token from email
Request Body
{ "token": "reset-token-from-email", "password": "NewSecureP@ssw0rd!" }

Frameworks & Controls

GET /api/frameworks List all available compliance frameworks
Response
{
  "success": true,
  "data": [
    { "id": "soc2", "name": "SOC 2 Type II", "controlCount": 63, "isActive": true },
    { "id": "iso27001", "name": "ISO 27001:2022", "controlCount": 94, "isActive": false }
  ]
}
GET /api/compliance/controls List all controls (optionally filter by frameworkId)
Query Parameters
frameworkIdFilter controls by framework (e.g., ?frameworkId=soc2)
statusFilter by controlStatus (NOT_STARTED, IN_REVIEW, COMPLETE, FAILED)
PATCH /api/compliance/controls/:id Update a control's ownership, status, or metadata
Request Body (all fields optional)
{
  "controlStatus": "IN_REVIEW",
  "ownerId": "clxr8k2vp0002lg3a",
  "dueDate": "2026-06-30T00:00:00.000Z",
  "testingFrequency": "QUARTERLY",
  "plainEnglish": "Updated plain-English description...",
  "evidenceRequirements": "Updated evidence requirements..."
}
GET /api/compliance/audit-workspace Get full audit workspace data with controls and evidence
Query Parameters
frameworkIdOptional — filter to a specific framework
POST /api/compliance/checklist/:itemId/approve Approve an evidence checklist item (ADMIN or AUDITOR)
Request Body
{} // No body required
POST /api/compliance/checklist/:itemId/reject Reject an evidence checklist item with a note (ADMIN or AUDITOR)
Request Body
{ "note": "Please provide the full IAM policy JSON, not just a screenshot." }
GET /api/compliance/controls/:id/comments Get all comments for a control
POST /api/compliance/controls/:id/comments Add a comment to a control
Request Body
{
  "body": "I've uploaded the MFA policy screenshot. Please review.",
  "type": "COMMENT"  // or "REQUEST_EVIDENCE"
}

Risks

GET /api/risks List all risks — includes sourceCheck and reopenCount
Response
{
  "success": true,
  "data": [
    {
      "id": "clxq1r2st0003lg9a",
      "title": "AWS S3 Public Bucket Exposure",
      "severity": "HIGH",
      "status": "OPEN",
      "likelihood": 4,
      "impact": 4,
      "reopenCount": 1,
      "lastReopenedAt": "2026-03-07T06:00:00.000Z",
      "sourceCheck": {
        "id": "clxq1r2st0004lg9a",
        "checkName": "S3 Public Bucket",
        "integration": { "name": "AWS Production" }
      }
    }
  ]
}
POST /api/risks Create a new risk manually
Request Body
{
  "title": "Weak password policy for service accounts",
  "description": "Several service accounts use passwords below the minimum complexity requirement.",
  "likelihood": 3,
  "impact": 4,
  "ownerId": "clxr8k2vp0002lg3a",
  "mitigationSteps": "1. Audit all service accounts\n2. Rotate weak passwords\n3. Enable IAM password policy",
  "dueDate": "2026-04-01T00:00:00.000Z"
}
PATCH /api/risks/:id Update a risk's status, mitigation steps, or other fields
Request Body (all fields optional)
{
  "status": "IN_PROGRESS",
  "mitigationSteps": "Updated mitigation plan..."
}
DELETE /api/risks/:id Delete a risk (ADMIN only)

Policies

GET /api/policies List all policies (ACTIVE + ARCHIVED + DRAFT for ADMINs; ACTIVE only for others)
POST /api/policies Create a new policy (ADMIN only)
Request Body
{
  "title": "Acceptable Use Policy",
  "content": "## Purpose\nThis policy defines acceptable use of company IT resources...\n\n## Scope\nAll employees and contractors...",
  "status": "DRAFT"  // or "ACTIVE" to publish immediately
}
PATCH /api/policies/:id Update or publish a policy (ADMIN only)
Request Body
{
  "status": "ACTIVE",  // Publishes the policy; auto-archives previous version
  "content": "Updated policy content..."
}
DELETE /api/policies/:id Delete a policy (ADMIN only — DRAFT only; cannot delete ACTIVE)

Integrations

GET /api/integrations List all connected integrations
Response
{
  "success": true,
  "data": [
    {
      "id": "clxs4t5uv0001lg0a",
      "name": "AWS Production",
      "type": "AWS",
      "isActive": true,
      "lastSyncAt": "2026-03-08T06:00:00.000Z",
      "checkSummary": { "pass": 5, "fail": 2, "warning": 1 }
    }
  ]
}
POST /api/integrations Add a new integration (ADMIN only)
Request Body
{
  "name": "AWS Production",
  "type": "AWS",  // AWS | GITHUB | AZURE | GCP | OKTA | GITLAB | GOOGLE_WORKSPACE | SLACK
  "credentials": {
    "accessKeyId": "AKIAIOSFODNN7EXAMPLE",
    "secretAccessKey": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY",
    "region": "us-east-1"
  }
}
Note

Credentials are encrypted with AES-256-GCM before storage and are never returned in API responses.

PATCH /api/integrations/:id Update integration name or credentials (ADMIN only)
DELETE /api/integrations/:id Remove an integration and all its check history (ADMIN only)
POST /api/integrations/:id/sync Trigger an immediate sync for this integration (ADMIN only)
Response
{
  "success": true,
  "message": "Sync started for AWS Production",
  "data": { "checksQueued": 7 }
}

Monitoring

GET /api/monitoring/summary Get high-level monitoring summary (compliance score, check counts)
Response
{
  "success": true,
  "data": {
    "complianceScore": 87,
    "lastScanAt": "2026-03-08T06:00:00.000Z",
    "checks": { "pass": 34, "fail": 4, "warning": 2, "info": 3 }
  }
}
GET /api/monitoring/checks List all integration checks with their latest status
GET /api/monitoring/trends Get sparkline trend data for all checks (last 10 runs)
Response
{
  "success": true,
  "data": [
    {
      "checkName": "AWS IAM MFA",
      "latestStatus": "PASS",
      "trend": "stable",  // stable | improving | degrading | flapping
      "sparkline": ["PASS", "PASS", "PASS", "PASS", "PASS", "PASS", "PASS", "PASS", "PASS", "PASS"]
    }
  ]
}
POST /api/monitoring/run-now Trigger an immediate scan of all integrations (ADMIN only)

Vendors

GET /api/vendors List all vendors with auto-calculated risk scores
POST /api/vendors Add a new vendor (ADMIN only)
Request Body
{
  "name": "Twilio",
  "website": "https://twilio.com",
  "category": "Communications",
  "dataAccess": ["PII"],
  "certifications": ["SOC2", "ISO27001"],
  "contractRenewalDate": "2026-12-01T00:00:00.000Z"
}
PATCH /api/vendors/:id Update vendor details (ADMIN only — risk score recalculated)
DELETE /api/vendors/:id Remove a vendor (ADMIN only)

Questionnaires

GET /api/questionnaires List all questionnaires for the organisation
POST /api/questionnaires Create a new questionnaire with raw question text
Request Body
{
  "title": "Acme Corp Vendor Assessment 2026",
  "requester": "Acme Corp",
  "questionsRaw": "1. Do you enforce MFA?\n2. When was your last pen test?\n3. Do you have SOC 2 Type II?"
}
POST /api/questionnaires/:id/auto-answer Run the auto-answer engine on all questions in this questionnaire
Request Body
{} // No body required
GET /api/questionnaires/:id/export Export completed questionnaire as plain text (.txt)

Returns: text/plain file with questions, answers, and confidence scores.

Trust Center

GET /api/trust-center/settings Get Trust Center configuration (ADMIN only)
PATCH /api/trust-center/settings Update Trust Center settings (ADMIN only)
Request Body
{
  "slug": "acme-corp",
  "isPublic": true,
  "customMessage": "We take security seriously. Contact security@acme.com for details."
}
GET /api/trust-center/public/:slug Get public Trust Center data — no authentication required
Response
{
  "success": true,
  "data": {
    "orgName": "Acme Corp",
    "customMessage": "We take security seriously.",
    "frameworks": [{ "name": "SOC 2 Type II", "completeCount": 58, "controlCount": 63 }],
    "controlReadinessScore": 92,
    "activePolicies": [{ "title": "Access Control Policy", "publishedAt": "2026-03-01T09:00:00.000Z" }],
    "lastUpdated": "2026-03-08T06:00:00.000Z"
  }
}

Export

GET /api/export/audit-bundle Download a complete audit bundle as a ZIP archive (ADMIN or AUDITOR)
Response

Binary ZIP file. Content-Type: application/zip. Filename: audit-bundle-YYYY-MM-DD.zip.

ZIP Contents
FileContents
summary.txtOrganisation name, date, control readiness %, risk counts, policy counts
controls.csvAll controls: code, title, status, owner, testingFrequency, dueDate, evidenceCount
risks.csvAll risks: title, severity, status, likelihood, impact, owner, dueDate, sourceCheck
evidence-checklist.csvAll checklist items: control, item name, status (APPROVED/REJECTED/PENDING), reviewedBy
policies.txtAll ACTIVE policies with version, publishedAt, and full content
Example curl command
curl -L \
  -H "Authorization: Bearer <token>" \
  -o audit-bundle.zip \
  https://app.zgovern.com/api/export/audit-bundle