Compliance API¶

The Compliance API provides endpoints for running automated compliance tests, configuring thresholds, and retrieving test results with cushion analysis.

Overview¶

CalcBridge's compliance testing automates the verification of CLO indenture requirements. Key features:

Automated Test Suites: Pre-configured tests for common compliance requirements
Threshold Management: Configure pass/fail thresholds per test
Cushion Analysis: Track distance to breach for proactive monitoring
Audit Trail: Complete logging of all test executions

Endpoints¶

Run Compliance Tests¶

Execute a compliance test suite against a workbook.

POST /api/v1/compliance/run

Request Body¶

Field	Type	Required	Description
`workbook_id`	string (UUID)	Yes	Workbook to test against
`test_suite`	string	No	Test suite name (default: "standard")
`test_ids`	array[string]	No	Specific test IDs to run (runs all if omitted)
`options`	object	No	Additional execution options

Options Object¶

Field	Type	Default	Description
`include_cushion`	boolean	true	Calculate cushion values
`fail_fast`	boolean	false	Stop on first failure
`parallel`	boolean	true	Run tests in parallel

Example Request¶

cURLPythonJavaScript

curl -X POST https://api.calcbridge.io/api/v1/compliance/run \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "workbook_id": "550e8400-e29b-41d4-a716-446655440000",
    "test_suite": "standard",
    "options": {
      "include_cushion": true,
      "fail_fast": false
    }
  }'

import requests

response = requests.post(
    "https://api.calcbridge.io/api/v1/compliance/run",
    headers={"Authorization": f"Bearer {token}"},
    json={
        "workbook_id": "550e8400-e29b-41d4-a716-446655440000",
        "test_suite": "standard",
        "options": {"include_cushion": True}
    }
)
result = response.json()
print(f"Passed: {result['summary']['passed']}/{result['summary']['total']}")

const response = await fetch('https://api.calcbridge.io/api/v1/compliance/run', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    workbook_id: '550e8400-e29b-41d4-a716-446655440000',
    test_suite: 'standard',
    options: { include_cushion: true }
  })
});
const result = await response.json();
console.log(`Passed: ${result.summary.passed}/${result.summary.total}`);

Response¶

{
  "id": "770e8400-e29b-41d4-a716-446655440002",
  "workbook_id": "550e8400-e29b-41d4-a716-446655440000",
  "test_suite": "standard",
  "status": "completed",
  "summary": {
    "total": 15,
    "passed": 13,
    "failed": 2,
    "warnings": 1,
    "skipped": 0
  },
  "results": [
    {
      "test_id": "concentration_single_obligor",
      "test_name": "Single Obligor Concentration",
      "category": "concentration",
      "status": "pass",
      "current_value": 4.2,
      "threshold_value": 5.0,
      "threshold_type": "max",
      "cushion": 0.8,
      "cushion_pct": 16.0,
      "message": "Single obligor concentration within limit"
    },
    {
      "test_id": "rating_ccc_bucket",
      "test_name": "CCC Rated Assets",
      "category": "rating",
      "status": "fail",
      "current_value": 8.5,
      "threshold_value": 7.5,
      "threshold_type": "max",
      "cushion": -1.0,
      "cushion_pct": -13.33,
      "message": "CCC rated assets exceed maximum threshold"
    }
  ],
  "executed_at": "2026-01-25T10:30:00Z",
  "execution_time_ms": 1523
}

Error Responses¶

Status	Error	Description
`404`	Workbook not found	Invalid workbook_id
`400`	Invalid test suite	Test suite does not exist
`409`	Test already running	Concurrent test execution in progress

Get Test Results¶

Retrieve results from a compliance test run.

GET /api/v1/compliance/results/{result_id}

Path Parameters¶

Parameter	Type	Description
`result_id`	string (UUID)	Compliance result ID

Query Parameters¶

Parameter	Type	Default	Description
`include_details`	boolean	true	Include full test details
`status_filter`	string	-	Filter by status (pass, fail, warning)
`category`	string	-	Filter by test category

Example Request¶

cURLPythonJavaScript

curl -X GET "https://api.calcbridge.io/api/v1/compliance/results/770e8400-e29b-41d4-a716-446655440002?status_filter=fail" \
  -H "Authorization: Bearer $TOKEN"

import requests

response = requests.get(
    f"https://api.calcbridge.io/api/v1/compliance/results/{result_id}",
    headers={"Authorization": f"Bearer {token}"},
    params={"status_filter": "fail"}
)
result = response.json()
for test in result["results"]:
    print(f"{test['test_name']}: {test['status']}")

const response = await fetch(
  `https://api.calcbridge.io/api/v1/compliance/results/${resultId}?status_filter=fail`,
  { headers: { 'Authorization': `Bearer ${token}` } }
);
const result = await response.json();
result.results.forEach(test => {
  console.log(`${test.test_name}: ${test.status}`);
});

Response¶

{
  "id": "770e8400-e29b-41d4-a716-446655440002",
  "workbook_id": "550e8400-e29b-41d4-a716-446655440000",
  "test_suite": "standard",
  "status": "completed",
  "summary": {
    "total": 15,
    "passed": 13,
    "failed": 2,
    "warnings": 1,
    "skipped": 0
  },
  "results": [
    {
      "test_id": "rating_ccc_bucket",
      "test_name": "CCC Rated Assets",
      "category": "rating",
      "status": "fail",
      "current_value": 8.5,
      "threshold_value": 7.5,
      "threshold_type": "max",
      "cushion": -1.0,
      "cushion_pct": -13.33,
      "message": "CCC rated assets exceed maximum threshold",
      "details": {
        "formula": "=SUMIF(Ratings, \"CCC*\", Par) / SUM(Par)",
        "cell_refs": ["Sheet1!G:G", "Sheet1!D:D"],
        "breakdown": {
          "ccc_par": 8500000,
          "total_par": 100000000
        }
      }
    }
  ],
  "executed_at": "2026-01-25T10:30:00Z",
  "execution_time_ms": 1523
}

List Test Suites¶

Get available compliance test suites.

GET /api/v1/compliance/suites

Query Parameters¶

Parameter	Type	Default	Description
`include_tests`	boolean	false	Include test definitions

Example Request¶

cURLPythonJavaScript

curl -X GET "https://api.calcbridge.io/api/v1/compliance/suites?include_tests=true" \
  -H "Authorization: Bearer $TOKEN"

import requests

response = requests.get(
    "https://api.calcbridge.io/api/v1/compliance/suites",
    headers={"Authorization": f"Bearer {token}"},
    params={"include_tests": True}
)
suites = response.json()
for suite in suites["items"]:
    print(f"{suite['name']}: {len(suite.get('tests', []))} tests")

const response = await fetch(
  'https://api.calcbridge.io/api/v1/compliance/suites?include_tests=true',
  { headers: { 'Authorization': `Bearer ${token}` } }
);
const suites = await response.json();
suites.items.forEach(suite => {
  console.log(`${suite.name}: ${(suite.tests || []).length} tests`);
});

Response¶

{
  "items": [
    {
      "id": "standard",
      "name": "Standard CLO Tests",
      "description": "Common compliance tests for CLO portfolios",
      "test_count": 15,
      "categories": ["concentration", "rating", "coverage", "portfolio"],
      "tests": [
        {
          "test_id": "concentration_single_obligor",
          "name": "Single Obligor Concentration",
          "category": "concentration",
          "description": "Maximum exposure to any single obligor",
          "default_threshold": 5.0,
          "threshold_type": "max"
        },
        {
          "test_id": "concentration_top_5",
          "name": "Top 5 Obligor Concentration",
          "category": "concentration",
          "description": "Combined exposure to top 5 obligors",
          "default_threshold": 20.0,
          "threshold_type": "max"
        }
      ]
    },
    {
      "id": "enhanced",
      "name": "Enhanced CLO Tests",
      "description": "Extended test suite with additional checks",
      "test_count": 25,
      "categories": ["concentration", "rating", "coverage", "portfolio", "liquidity"]
    }
  ],
  "total": 2
}

Configure Thresholds¶

Set custom thresholds for compliance tests.

POST /api/v1/compliance/thresholds

Request Body¶

Field	Type	Required	Description
`workbook_id`	string (UUID)	No	Workbook-specific thresholds
`test_id`	string	Yes	Test identifier
`threshold_value`	number	Yes	Threshold value
`threshold_type`	string	No	Type: "min", "max", "exact"
`warning_threshold`	number	No	Warning level threshold
`enabled`	boolean	No	Enable/disable test (default: true)

Example Request¶

cURLPythonJavaScript

curl -X POST https://api.calcbridge.io/api/v1/compliance/thresholds \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "workbook_id": "550e8400-e29b-41d4-a716-446655440000",
    "test_id": "concentration_single_obligor",
    "threshold_value": 4.5,
    "threshold_type": "max",
    "warning_threshold": 4.0
  }'

import requests

response = requests.post(
    "https://api.calcbridge.io/api/v1/compliance/thresholds",
    headers={"Authorization": f"Bearer {token}"},
    json={
        "workbook_id": "550e8400-e29b-41d4-a716-446655440000",
        "test_id": "concentration_single_obligor",
        "threshold_value": 4.5,
        "threshold_type": "max",
        "warning_threshold": 4.0
    }
)
threshold = response.json()
print(f"Threshold set: {threshold['threshold_value']}")

const response = await fetch('https://api.calcbridge.io/api/v1/compliance/thresholds', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    workbook_id: '550e8400-e29b-41d4-a716-446655440000',
    test_id: 'concentration_single_obligor',
    threshold_value: 4.5,
    threshold_type: 'max',
    warning_threshold: 4.0
  })
});
const threshold = await response.json();
console.log('Threshold set:', threshold.threshold_value);

Response¶

{
  "id": "880e8400-e29b-41d4-a716-446655440003",
  "workbook_id": "550e8400-e29b-41d4-a716-446655440000",
  "test_id": "concentration_single_obligor",
  "threshold_value": 4.5,
  "threshold_type": "max",
  "warning_threshold": 4.0,
  "enabled": true,
  "created_at": "2026-01-25T10:30:00Z",
  "updated_at": "2026-01-25T10:30:00Z"
}

Get Thresholds¶

Retrieve configured thresholds.

GET /api/v1/compliance/thresholds

Query Parameters¶

Parameter	Type	Description
`workbook_id`	string (UUID)	Filter by workbook
`test_id`	string	Filter by test ID
`category`	string	Filter by test category

Example Request¶

cURLPythonJavaScript

curl -X GET "https://api.calcbridge.io/api/v1/compliance/thresholds?workbook_id=550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer $TOKEN"

import requests

response = requests.get(
    "https://api.calcbridge.io/api/v1/compliance/thresholds",
    headers={"Authorization": f"Bearer {token}"},
    params={"workbook_id": "550e8400-e29b-41d4-a716-446655440000"}
)
thresholds = response.json()
for t in thresholds["items"]:
    print(f"{t['test_id']}: {t['threshold_value']}")

const response = await fetch(
  `https://api.calcbridge.io/api/v1/compliance/thresholds?workbook_id=${workbookId}`,
  { headers: { 'Authorization': `Bearer ${token}` } }
);
const thresholds = await response.json();
thresholds.items.forEach(t => {
  console.log(`${t.test_id}: ${t.threshold_value}`);
});

Response¶

{
  "items": [
    {
      "id": "880e8400-e29b-41d4-a716-446655440003",
      "workbook_id": "550e8400-e29b-41d4-a716-446655440000",
      "test_id": "concentration_single_obligor",
      "threshold_value": 4.5,
      "threshold_type": "max",
      "warning_threshold": 4.0,
      "enabled": true
    },
    {
      "id": "880e8400-e29b-41d4-a716-446655440004",
      "workbook_id": "550e8400-e29b-41d4-a716-446655440000",
      "test_id": "rating_ccc_bucket",
      "threshold_value": 7.5,
      "threshold_type": "max",
      "warning_threshold": 6.0,
      "enabled": true
    }
  ],
  "total": 2
}

List Test History¶

Get historical compliance test results.

GET /api/v1/compliance/history

Query Parameters¶

Parameter	Type	Default	Description
`workbook_id`	string (UUID)	-	Filter by workbook
`test_suite`	string	-	Filter by test suite
`status`	string	-	Filter by status
`start_date`	string (ISO 8601)	-	Results after this date
`end_date`	string (ISO 8601)	-	Results before this date
`page`	integer	1	Page number
`page_size`	integer	20	Items per page

Example Request¶

cURL

curl -X GET "https://api.calcbridge.io/api/v1/compliance/history?workbook_id=550e8400-e29b-41d4-a716-446655440000&page_size=10" \
  -H "Authorization: Bearer $TOKEN"

Response¶

{
  "items": [
    {
      "id": "770e8400-e29b-41d4-a716-446655440002",
      "workbook_id": "550e8400-e29b-41d4-a716-446655440000",
      "test_suite": "standard",
      "status": "completed",
      "summary": {
        "total": 15,
        "passed": 13,
        "failed": 2
      },
      "executed_at": "2026-01-25T10:30:00Z"
    },
    {
      "id": "770e8400-e29b-41d4-a716-446655440001",
      "workbook_id": "550e8400-e29b-41d4-a716-446655440000",
      "test_suite": "standard",
      "status": "completed",
      "summary": {
        "total": 15,
        "passed": 14,
        "failed": 1
      },
      "executed_at": "2026-01-24T10:30:00Z"
    }
  ],
  "total": 25,
  "page": 1,
  "page_size": 10,
  "pages": 3
}

Test Categories¶

Category	Description	Example Tests
`concentration`	Obligor/industry concentration	Single obligor, Top 5, Industry limits
`rating`	Credit rating thresholds	CCC bucket, Average rating
`coverage`	Coverage ratio tests	OC test, IC test
`portfolio`	Portfolio composition	WAL, WAS, Diversity score
`liquidity`	Liquidity requirements	Cash reserve, Principal proceeds

Cushion Calculation¶

Cushion represents the distance between the current value and the threshold:

Positive cushion: Passing with headroom
Zero cushion: At threshold boundary
Negative cushion: Failing (breach)

Calculation Formula¶

For maximum thresholds:

cushion = threshold_value - current_value
cushion_pct = (cushion / threshold_value) * 100

For minimum thresholds:

cushion = current_value - threshold_value
cushion_pct = (cushion / threshold_value) * 100

Webhooks¶

Configure webhooks to receive notifications on compliance events:

compliance.test.completed - Test run completed
compliance.test.failed - Test run had failures
compliance.threshold.breach - Threshold was breached
compliance.threshold.warning - Approaching threshold

See Alerts API for webhook configuration.