Custom Frameworks API

Build your own compliance frameworks with custom controls, evidence requirements, and standard mappings. Publish them, run assessments, clone from existing frameworks, and import/export as JSON or CSV. Requires Scale tier or higher. All endpoints require JWT authentication.

Framework CRUD

POST /api/v1/custom-frameworks 🔒
Create a new custom framework.

Request Body

FieldTypeRequiredDescription
namestringYesFramework name
descriptionstringNoDescription
versionstringNoVersion label (e.g. "1.0")
categorystringNocustom, industry, internal, regulatory
 
curl -X POST https://api.privabase.com/api/v1/custom-frameworks \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Internal Security Standard",
    "description": "Company-wide security controls",
    "version": "1.0",
    "category": "internal"
  }'
// JavaScript
const res = await fetch('https://api.privabase.com/api/v1/custom-frameworks', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: 'Internal Security Standard',
    description: 'Company-wide security controls',
    version: '1.0',
    category: 'internal'
  })
});
const { data } = await res.json();
# Python
resp = requests.post('https://api.privabase.com/api/v1/custom-frameworks',
    headers={'Authorization': 'Bearer YOUR_TOKEN'},
    json={
        'name': 'Internal Security Standard',
        'description': 'Company-wide security controls',
        'version': '1.0',
        'category': 'internal'
    })
framework = resp.json()['data']

Response 201

{
  "success": true,
  "data": {
    "id": "cf-abc-123",
    "name": "Internal Security Standard",
    "description": "Company-wide security controls",
    "version": "1.0",
    "category": "internal",
    "status": "draft",
    "created_at": "2026-03-14T10:30:00Z"
  }
}
GET /api/v1/custom-frameworks 🔒
List all custom frameworks for the account.
curl https://api.privabase.com/api/v1/custom-frameworks \
  -H "Authorization: Bearer YOUR_TOKEN"
GET /api/v1/custom-frameworks/:id 🔒
Get a framework with all its controls.
curl https://api.privabase.com/api/v1/custom-frameworks/cf-abc-123 \
  -H "Authorization: Bearer YOUR_TOKEN"
PUT /api/v1/custom-frameworks/:id 🔒
Update framework metadata (name, description, version, category).
curl -X PUT https://api.privabase.com/api/v1/custom-frameworks/cf-abc-123 \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Internal Security Standard v2", "version": "2.0" }'
DELETE /api/v1/custom-frameworks/:id 🔒
Soft-delete a custom framework.
curl -X DELETE https://api.privabase.com/api/v1/custom-frameworks/cf-abc-123 \
  -H "Authorization: Bearer YOUR_TOKEN"

Controls

POST /api/v1/custom-frameworks/:id/controls 🔒
Add a control to the framework.

Request Body

FieldTypeRequiredDescription
control_id_labelstringYesControl identifier (e.g. "ISS-1.1")
titlestringYesControl title
descriptionstringNoDetailed description
categorystringNoControl category
evidence_requirementsstringNoWhat evidence is needed
test_criteriastringNoPass/fail criteria
standard_mappingsarrayNoMappings to standard controls
sort_orderintegerNoDisplay order
 
curl -X POST https://api.privabase.com/api/v1/custom-frameworks/cf-abc-123/controls \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "control_id_label": "ISS-1.1",
    "title": "Multi-Factor Authentication",
    "description": "All user accounts must use MFA",
    "category": "access-control",
    "evidence_requirements": "Screenshot of MFA policy configuration"
  }'
PUT /api/v1/custom-frameworks/:id/controls/:cid 🔒
Update a control's properties.
DELETE /api/v1/custom-frameworks/:id/controls/:cid 🔒
Remove a control from the framework.
PUT /api/v1/custom-frameworks/:id/controls/reorder 🔒
Reorder controls by providing an ordered array of control IDs.

Request Body

{ "controlIds": ["ctrl-1", "ctrl-3", "ctrl-2"] }

Lifecycle

POST /api/v1/custom-frameworks/:id/publish 🔒
Publish a framework. Locks the control structure and enables assessments.
curl -X POST https://api.privabase.com/api/v1/custom-frameworks/cf-abc-123/publish \
  -H "Authorization: Bearer YOUR_TOKEN"
POST /api/v1/custom-frameworks/:id/clone 🔒
Clone an existing framework (built-in or custom) into a new custom framework.

Request Body

{ "name": "My SOC 2 Variant" }
curl -X POST https://api.privabase.com/api/v1/custom-frameworks/cf-abc-123/clone \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "name": "My SOC 2 Variant" }'

Import & Export

POST /api/v1/custom-frameworks/import 🔒
Import a framework from JSON or CSV format.

Request Body

FieldTypeRequiredDescription
formatstringYesjson or csv
dataobjectYesFramework data in the specified format
 
curl -X POST https://api.privabase.com/api/v1/custom-frameworks/import \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "format": "json",
    "data": {
      "name": "Imported Framework",
      "controls": [
        { "control_id_label": "C-1", "title": "Access Control" }
      ]
    }
  }'
GET /api/v1/custom-frameworks/:id/export 🔒
Export a framework as JSON (including all controls and mappings).
curl https://api.privabase.com/api/v1/custom-frameworks/cf-abc-123/export \
  -H "Authorization: Bearer YOUR_TOKEN"

Assessments

POST /api/v1/custom-frameworks/:id/assess 🔒
Run an assessment against a published custom framework. Evaluates all controls against collected evidence.
curl -X POST https://api.privabase.com/api/v1/custom-frameworks/cf-abc-123/assess \
  -H "Authorization: Bearer YOUR_TOKEN"
GET /api/v1/custom-frameworks/:id/assessment 🔒
Get the latest assessment results for a custom framework.
curl https://api.privabase.com/api/v1/custom-frameworks/cf-abc-123/assessment \
  -H "Authorization: Bearer YOUR_TOKEN"

Suggest Mappings

POST /api/v1/custom-frameworks/suggest-mappings 🔒
Get suggested standard control mappings based on a control's title and description.

Request Body

FieldTypeRequiredDescription
titlestringYesControl title
descriptionstringNoControl description
categorystringNoControl category
 
curl -X POST https://api.privabase.com/api/v1/custom-frameworks/suggest-mappings \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "title": "Multi-Factor Authentication", "category": "access-control" }'

Response

{
  "success": true,
  "data": [
    { "framework": "soc2", "controlId": "CC6.1", "controlName": "Logical Access Controls", "confidence": 0.92 },
    { "framework": "iso27001", "controlId": "A.9.4.2", "controlName": "Secure log-on procedures", "confidence": 0.87 }
  ]
}

PrivaBase API v1.3.0 · privabase.com