Compliance API

All endpoints require authentication via X-API-Key header or JWT Bearer token. The base URL is https://codestax.co/api.

This API mirrors the in-app compliance dashboard. Use it to wire compliance configuration into CI/CD, GRC tooling, or internal automation — so a customer’s audit-prep workflow doesn’t depend on clicking through the UI.

Framework Selection

List frameworks

Returns every framework available to the org (built-in + custom) along with each one’s enabled state, plan-lock state, and recommended-plan tier.


GET /api/compliance/frameworks


curl -H "X-API-Key: YOUR_API_KEY" https://codestax.co/api/compliance/frameworks

Response:


{
  "available": [
    {
      "key": "soc2",
      "name": "SOC 2 Type II",
      "description": "Service Organization Controls",
      "control_count": 15,
      "custom": false,
      "enabled": true,
      "requires_plan": null,
      "plan_locked": false
    },
    {
      "key": "hipaa",
      "name": "HIPAA",
      "description": "Health Information Privacy",
      "control_count": 6,
      "custom": false,
      "enabled": false,
      "requires_plan": "enterprise",
      "plan_locked": true
    }
  ],
  "enabled_keys": ["soc2", "owasp"],
  "default_all_enabled": false,
  "frameworks": [...]
}

Field	Type	Description
`available`	array	All frameworks visible to the org
`enabled_keys`	array \| null	Explicit selection. `null` means default (every framework on).
`default_all_enabled`	boolean	Convenience flag — true when `enabled_keys` is null
`frameworks`	array	Legacy shape, kept for backward compatibility

Each available[] entry:

Field	Type	Description
`key`	string	Stable identifier (`soc2`, `iso27001`, `owasp`, `pcidss`, `hipaa`, `nist_csf`, or custom)
`name`	string	Human-readable name
`description`	string	One-line description
`control_count`	integer	Number of controls in the framework
`custom`	boolean	True for org-defined custom frameworks
`enabled`	boolean	Currently active for this org
`requires_plan`	string \| null	Minimum plan tier required (e.g. `"enterprise"` for HIPAA)
`plan_locked`	boolean	True when org’s plan can’t enable this framework

Set enabled frameworks

Org Admin or Owner role required. Saving a non-permitted framework on a lower-tier plan returns 402 Payment Required with a structured upgrade-prompt body.


PUT /api/compliance/frameworks/enabled
Content-Type: application/json

Request body:


{
  "keys": ["soc2", "owasp", "pcidss"]
}

Body shape	Effect
`{"keys": ["..."]}`	Explicit selection. Only the listed frameworks score against the org.
`{"keys": []}`	Org has actively opted out of every framework.
`{"keys": null}`	Reset to default (every framework enabled).

Response 200:


{
  "message": "Enabled frameworks updated",
  "enabled_keys": ["soc2", "owasp", "pcidss"],
  "default_all_enabled": false
}

Response 402 — plan upgrade required:


{
  "detail": {
    "error": "plan_upgrade_required",
    "message": "Framework 'hipaa' requires the Enterprise plan",
    "framework_key": "hipaa",
    "current_plan": "team",
    "required_plan": "enterprise"
  }
}

Response 403 — non-admin: {"detail": "Org admin role required"}


curl -X PUT \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"keys": ["soc2", "owasp"]}' \
  https://codestax.co/api/compliance/frameworks/enabled

Per-Control Selection

List controls (with recommendations)

Returns every control of a framework, the org’s per-control disabled status, and a recommendation badge (required / recommended / optional) plus reason.


GET /api/compliance/frameworks/{framework_key}/controls?repo_id={id}

The optional repo_id query parameter refines recommendations using the repository’s latest scan findings.


curl -H "X-API-Key: YOUR_API_KEY" \
  "https://codestax.co/api/compliance/frameworks/soc2/controls?repo_id=7"

Response:


{
  "framework_key": "soc2",
  "framework_name": "SOC 2 Type II",
  "custom": false,
  "controls": [
    {
      "id": "CC6.1",
      "name": "Logical & Physical Access Controls",
      "category": "Access",
      "description": "Ensure no hardcoded credentials or API keys in code",
      "check_type": "secrets",
      "disabled": false,
      "recommendation": "required",
      "recommendation_reason": "Credential leakage is a baseline control for any codebase."
    }
  ],
  "disabled_count": 2
}

Field	Type	Description
`disabled`	boolean	True when this control is marked Not Applicable for this org
`recommendation`	string	`required` (red) — keep enabled; `recommended` (blue) — keep enabled if your stack matches; `optional` (gray) — niche
`recommendation_reason`	string	One-line explanation, refined by scan data when `repo_id` is supplied

Recommendation refinement signals (only active when repo_id is supplied): real findings against the control auto-promote to required; repo language matching the control’s domain (Python → crypto, Java → auth) upgrades it; presence of Dockerfile/Terraform/CloudFormation findings promotes IaC controls. Without scan data, the engine falls back to static baseline rules.

Set disabled controls

Org Admin or Owner role required. Disabled controls are excluded from scoring entirely (they don’t count as pass, partial, or fail).


PUT /api/compliance/frameworks/{framework_key}/controls
Content-Type: application/json

Request body:


{
  "disabled": ["CC8.1", "CC2.1"]
}

Body shape	Effect
`{"disabled": [...]}`	Mark these control IDs Not Applicable. Replaces any previous selection for this framework.
`{"disabled": []}`	Re-enable every control in this framework.

Response 200:


{
  "message": "Control selection updated",
  "framework_key": "soc2",
  "disabled": ["CC8.1", "CC2.1"]
}

Response 403 — non-admin: {"detail": "Org admin role required"}

Response 400 — unknown control: {"detail": "Unknown control: CC99.9"}


curl -X PUT \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"disabled": ["CC8.1"]}' \
  https://codestax.co/api/compliance/frameworks/soc2/controls

Custom Frameworks

Create custom framework

Define a framework specific to your organization. Custom frameworks appear alongside built-ins in the picker and on the dashboard.


POST /api/compliance/custom-frameworks
Content-Type: application/json

Request body:


{
  "name": "Internal Security Policy",
  "key": "internal_sec",
  "controls": [
    {
      "id": "ISP-1",
      "name": "No hardcoded secrets",
      "category": "Credentials",
      "description": "All credentials live in the secret manager.",
      "check_type": "secrets",
      "pass_condition": "no_critical_secrets"
    }
  ]
}

Valid check_type values: secrets, sast_security, sast_crypto, sast_auth, scan_recency, quality_gates, pr_reviews, sca_vulns, code_quality, iac_issues.

Response 200:


{
  "message": "Framework saved",
  "key": "internal_sec",
  "name": "Internal Security Policy"
}

If your org has an explicit enabled_keys selection, the new custom framework is automatically added to it (so it appears immediately on the dashboard).

List custom frameworks


GET /api/compliance/custom-frameworks

Response:


{
  "frameworks": [
    {
      "id": 12,
      "key": "internal_sec",
      "name": "Internal Security Policy",
      "controls": [...],
      "created_at": "2026-04-26T..."
    }
  ]
}

Delete custom framework


DELETE /api/compliance/custom-frameworks/{framework_key}


curl -X DELETE \
  -H "X-API-Key: YOUR_API_KEY" \
  https://codestax.co/api/compliance/custom-frameworks/internal_sec

Response 200: {"message": "Framework deleted"}

If the deleted key was in the org’s enabled list, it’s removed automatically (no stale references).

Compliance Scores

Get scores for a repository

Returns scores for every enabled framework, scoped to one repository’s latest scan. Disabled controls are excluded.


GET /api/compliance/score/{repo_id}

Optional query: ?framework=soc2 to limit the response to one framework.

Response:


{
  "repo_id": 7,
  "repo_name": "checkout-service",
  "evaluated_at": "2026-04-26T...",
  "last_scan": "2026-04-26 ...",
  "total_issues": 18,
  "executive_summary": {
    "overall_score": 72,
    "total_controls": 30,
    "passing": 19,
    "partial": 6,
    "failing": 5,
    "posture": "Moderate",
    "risk_areas": [...],
    "recommendation": "Address failing controls in pcidss"
  },
  "frameworks": {
    "soc2": {
      "name": "SOC 2 Type II",
      "score": 78,
      "pass": 11,
      "partial": 3,
      "fail": 1,
      "total": 15,
      "controls": [...]
    }
  }
}

Get score trend


GET /api/compliance/trend/{repo_id}?framework=soc2&days=90

Returns scores at each completed scan over the requested window. Disabled frameworks return 400.

Audit Logging

Every PUT/POST/DELETE on this API writes an AuditLogSaaS entry visible at /dashboard/audit-logs.

Endpoint	Action code
`PUT /compliance/frameworks/enabled`	`COMPLIANCE_FRAMEWORKS_UPDATED`
`PUT /compliance/frameworks/{key}/controls`	`COMPLIANCE_CONTROLS_UPDATED`
`POST /compliance/custom-frameworks`	`COMPLIANCE_CUSTOM_FRAMEWORK_CREATED`
`DELETE /compliance/custom-frameworks/{key}`	`COMPLIANCE_CUSTOM_FRAMEWORK_DELETED`

Each entry includes actor email, IP, user agent, and structured metadata of the change.

Integration Patterns

CI/CD compliance check

Run a compliance check from your pipeline; fail the build when score drops below a threshold.


SCORE=$(curl -s -H "X-API-Key: $CODESTAX_API_KEY" \
  "https://codestax.co/api/compliance/score/$REPO_ID" \
  | jq '.executive_summary.overall_score')
 
if [ "$SCORE" -lt 70 ]; then
  echo "Compliance score $SCORE below threshold 70"
  exit 1
fi

Wire your provisioning flow to set the framework selection based on the customer’s industry.


curl -X PUT \
  -H "X-API-Key: $CODESTAX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"keys": ["soc2", "hipaa", "owasp"]}' \
  https://codestax.co/api/compliance/frameworks/enabled

Sync custom frameworks from your GRC tool

Pull control definitions from your GRC tool, push them as a custom framework.


import httpx
 
GRC_CONTROLS = grc_client.list_controls()
controls = [
    {
        "id": c.id,
        "name": c.name,
        "category": c.category,
        "check_type": "scan_recency",  # map your GRC types -> ours
        "pass_condition": "scanned_within_7_days",
    }
    for c in GRC_CONTROLS
]
 
httpx.post(
    "https://codestax.co/api/compliance/custom-frameworks",
    headers={"X-API-Key": API_KEY},
    json={"name": "Acme GRC", "key": "acme_grc", "controls": controls},
)

Compliance API

Framework Selection

List frameworks

Set enabled frameworks

Per-Control Selection

List controls (with recommendations)

Set disabled controls

Custom Frameworks

Create custom framework

List custom frameworks

Delete custom framework

Compliance Scores

Get scores for a repository

Get score trend

Audit Logging

Integration Patterns

CI/CD compliance check

Automated framework enablement on signup

Sync custom frameworks from your GRC tool

Related