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

Admin: Stream Profiles¶

Stream profiles define per‑deal retention and jurisdiction overrides that drive evidence storage policies. These endpoints require an admin or owner role.

List Stream Profiles¶

GET /api/v1/admin/compliance/stream-profiles

Query Parameters¶

Parameter	Type	Description
`stream_key`	string	Optional filter by stream key
`page`	integer	Page number (default 1)
`page_size`	integer	Page size (default 50)

Create Stream Profile¶

POST /api/v1/admin/compliance/stream-profiles

Request Body¶

Field	Type	Required	Description
`stream_key`	string	Yes	Deal/stream identifier
`deal_name`	string	No	Human‑friendly deal name
`jurisdiction`	string	No	Jurisdiction code (e.g., `EU`, `US`, `UK`)
`retention_mode`	string	No	`fixed_years` or `life_of_securitisation`
`retention_years`	integer	No	Override retention years
`maturity_date`	date	No	Used for `life_of_securitisation` mode
`retention_until`	datetime	No	Explicit retention timestamp
`profile_metadata`	object	No	Optional metadata (e.g., tranche identifiers)

Update Stream Profile¶

PATCH /api/v1/admin/compliance/stream-profiles/{profile_id}

Delete Stream Profile¶

DELETE /api/v1/admin/compliance/stream-profiles/{profile_id}

Evidence Lookback¶

Reconstruct historical compliance decisions with evidence context.

List Lookback Timeline (GET)¶

GET /api/v1/compliance/lookback

Query parameters mirror the lookback filters (event_type, event_category, subject_id, actor_id, stream_key, start_date, end_date, plus include_* flags).

Lookback Timeline (POST)¶

POST /api/v1/compliance/evidence/lookback

Use the POST variant when filters are too large for query strings. The JSON body matches the GET parameters and supports pagination via offset and limit.

Notes¶

Recommended stream_key format: deal:<scheme>:<id> where <scheme> is the identifier authority (e.g., sui for EU/UK securitisation unique identifier, sec for SEC accession, trustee for internal trustee deal IDs). Example: deal:sui:ESMA-2023-001234.
Store tranche identifiers in profile_metadata.tranches as a list of { "scheme": "ISIN" | "CUSIP", "value": "…" }. This keeps retention policies deal‑level while preserving tranche lookup data.
effective_retention_until is computed using the retention policy engine.
Jurisdiction‑based minimums act as a floor even when retention_years is shorter. Defaults are 5 years for US/SEC/UK/EU unless overridden via CALCBRIDGE_EVIDENCE_JURISDICTION_MIN_YEARS.
Stream key validation is enforced by default; adjust CALCBRIDGE_STREAM_KEY_* settings to loosen or expand allowed schemes.

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.