Skip to main content
POST
/
api
/
audits
Create Audit
curl --request POST \
  --url https://api.example.com/api/audits \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "<string>",
  "policy_type": "<string>",
  "selected_categories": [
    "<string>"
  ]
}
'
{
  "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

​
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

Build docs developers (and LLMs) love

Get started for freeTalk to us