Skip to main content
All API endpoints live as Next.js API routes at /api/. There is no separate backend server.

Authentication

Every protected endpoint requires a valid BetterAuth session. The session is established via cookie-based authentication after login.
Browser → POST /api/auth/sign-in → Session cookie set
       → Subsequent requests include session cookie automatically
API routes extract the session and organization context:
const session = await getSession()    // Returns null if not authenticated
const orgId = getOrgId(session)       // Extracts active organization ID
All tenant-scoped queries filter by orgId for multi-tenant isolation.

Request format

JSON body

POST and PATCH endpoints accept JSON request bodies:
curl -X POST /api/examinations \
  -H "Content-Type: application/json" \
  -d '{"type": "regulatory", "examiner": "FDIC", "responseDeadline": "2026-03-15"}'

File uploads

Evidence and document upload endpoints accept multipart/form-data:
curl -X POST /api/examinations/EX-2026-001/upload \
  -F "file=@request-letter.pdf"
Maximum file size: 50 MB. Allowed types: PDF, DOCX, XLSX, CSV, PNG, JPG.

Query parameters

GET endpoints use query parameters for filtering and pagination:
GET /api/knowledge-base/browse?domain=bsa_aml&limit=20&offset=0
GET /api/mras?status=open,remediation_in_progress

Response format

Success

{
  "data": {
    "examination": {
      "id": "EX-2026-001",
      "name": "Q1 BSA Examination",
      "status": "in_progress"
    }
  }
}
List endpoints wrap results in a named array:
{
  "data": {
    "examinations": [...]
  }
}

Errors

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Examination not found"
  }
}

Status codes

CodeMeaning
200Success
201Created
400Bad request — validation error or missing required fields
401Unauthorized — no valid session
403Forbidden — archived resource or insufficient permissions
404Not found — resource doesn’t exist or doesn’t belong to your org
409Conflict — duplicate resource or invalid status transition
500Internal server error
503Service unavailable — background service unavailable

ID formats

Verity uses human-readable IDs throughout:
ResourceFormatExample
ExaminationEX-YYYY-NNNEX-2026-001
Request itemRI-NNNRI-001
MRAMRA-YYYY-NNNMRA-2026-001
Compliance programCP-YYYY-NNNCP-2026-001
IDs are globally unique across all organizations.