Create Audit

Create a new compliance audit with a prebuilt policy pack (AML, GDPR, or SOC2)

POST /api/audits

Create Audit

cURL

curl --request POST \
  --url https://api.example.com/api/audits \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "<string>",
  "policy_type": "<string>",
  "selected_categories": [
    "<string>"
  ]
}
'

200

{
  "audit_id": "<string>",
  "policy_id": "<string>",
  "rules": [
    {
      "rule_id": "<string>",
      "name": "<string>",
      "type": "<string>",
      "description": "<string>",
      "threshold": 123,
      "time_window": "<string>",
      "severity": "<string>",
      "conditions": {},
      "policy_excerpt": "<string>",
      "policy_section": "<string>",
      "category": "<string>",
      "historical_context": "<string>"
    }
  ],
  "error": "<string>",
  "message": "<string>",
  "details": {}
}

Endpoint

POST /api/audits

Authentication

Requires a valid JWT token in the Authorization header or authenticated session cookies.

See Authentication for details.

Request Body

name · string · required

The name of the audit (e.g., “Q4 2024 SOC2 Audit”)

policy_type · string · required

The prebuilt policy pack to use. Must be one of:

• aml - Anti-Money Laundering rules
• gdpr - General Data Protection Regulation rules
• soc2 - SOC 2 compliance rules

selected_categories · string[]

Array of category names to filter rules. If provided, only rules matching these categories will be included in the audit.

Example: ["Access Control", "Encryption"]

Response

audit_id · string

Unique identifier for the created audit session (UUID v4)

policy_id · string

Database ID of the created policy record (UUID v4)

rules · Rule[]

Array of compliance rules loaded from the selected policy pack

Show Rule object properties

rule_id · string

Unique rule identifier

name · string

Human-readable rule name

type · string

Rule type (e.g., “threshold”, “pattern”, “anomaly”)

description · string

Rule description and context

threshold · number

Numeric threshold for threshold-based rules

time_window · string

Time window for temporal rules (e.g., “24h”, “7d”)

severity · string

Rule severity level: “low”, “medium”, “high”, or “critical”

conditions · object

Additional rule conditions as key-value pairs

policy_excerpt · string

Relevant excerpt from the policy document

policy_section · string

Section reference in the original policy document

category · string

Rule category for filtering and organization

historical_context · string

Historical context or rationale for the rule

Example Request

cURL

curl -X POST https://your-domain.com/api/audits \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Q4 2024 SOC2 Compliance Audit",
    "policy_type": "soc2",
    "selected_categories": ["Access Control", "Encryption"]
  }'

JavaScript

const { data: { session } } = await supabase.auth.getSession();

const response = await fetch('/api/audits', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${session.access_token}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    name: 'Q4 2024 SOC2 Compliance Audit',
    policy_type: 'soc2',
    selected_categories: ['Access Control', 'Encryption'],
  }),
});

const data = await response.json();
console.log('Audit created:', data.audit_id);
console.log('Loaded rules:', data.rules.length);

Example Response

201 Created

{
  "audit_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "policy_id": "a1b2c3d4-e5f6-7890-ab12-cd34ef567890",
  "rules": [
    {
      "rule_id": "soc2-ac-001",
      "name": "Multi-Factor Authentication Required",
      "type": "boolean",
      "description": "All user accounts must have MFA enabled",
      "severity": "high",
      "category": "Access Control",
      "policy_excerpt": "The organization shall require multi-factor authentication for all system access.",
      "policy_section": "CC6.1",
      "conditions": {
        "mfa_enabled": true
      }
    },
    {
      "rule_id": "soc2-enc-001",
      "name": "Data Encryption at Rest",
      "type": "boolean",
      "description": "All sensitive data must be encrypted at rest",
      "severity": "critical",
      "category": "Encryption",
      "policy_excerpt": "Sensitive data shall be encrypted using industry-standard algorithms.",
      "policy_section": "CC6.7",
      "conditions": {
        "encryption_enabled": true,
        "algorithm": "AES-256"
      }
    }
  ]
}

Error Responses

error · string

Error code identifying the type of error

message · string

Human-readable error message

details · object

Additional error details (for validation errors)

400 Validation Error

{
  "error": "VALIDATION_ERROR",
  "message": "Invalid request body",
  "details": [
    {
      "path": ["policy_type"],
      "message": "Invalid enum value. Expected 'aml' | 'gdpr' | 'soc2'"
    }
  ]
}

401 Unauthorized

{
  "error": "UNAUTHORIZED",
  "message": "Not authenticated — no valid session found"
}

500 Internal Error

{
  "error": "INTERNAL_ERROR",
  "message": "Failed to create policy"
}

Implementation Details

Database Operations

The endpoint performs the following operations:

1. Validates request using CreateAuditSchema (Zod validation)
2. Authenticates user via getUserIdFromRequest()
3. Loads policy pack based on policy_type (AML, GDPR, or SOC2)
4. Filters rules by selected_categories if provided
5. Creates policy record in the policies table
6. Inserts rules into the rules table with enriched metadata
7. Returns audit session with audit ID, policy ID, and rule array

Row-Level Security

All database operations respect RLS policies:

• policies table: user_id = auth.uid()
• rules table: Filtered by policy_id owned by the authenticated user

Custom PDF-based policies are handled by separate endpoints:

• /api/policies/ingest - Extract rules from PDF documents
• /api/policies/generate-rules - Generate rules using AI

This endpoint only supports prebuilt policy packs.

Notes

• The audit_id is a logical session identifier, not stored in the database (MVP design)
• Rule descriptions are enriched with historical_context metadata stored as JSON
• All rules are set to is_active: true by default
• Policy status is set to active and type to prebuilt