Code Health API

Corbulo continuously scores your codebase across 8 categories: security, runtime risks, test coverage, code smells, duplication, dead code, codebase consistency, and compliance. The Code Health API provides access to assessments, drift alerts, and the underlying analysis issues.

Get Health Dashboard

Returns the comprehensive health dashboard for a project, including the latest assessment, trend data, drift alerts, codebase dynamics, convention consistency, and test quality metrics.

curl "https://app.corbulo.dev/api/v1/projects/b3d7f1a2-4e5c-6d8a-9b0c-1e2f3a4b5c6d/health" \
  -H "Authorization: Bearer ok_live_a1b2c3d4e5f6..."

{
  "latest_assessment": {
    "id": "a1b2c3d4-5678-9abc-def0-111111111111",
    "project_id": "b3d7f1a2-4e5c-6d8a-9b0c-1e2f3a4b5c6d",
    "overall_score": 78.5,
    "overall_grade": "B",
    "security_score": 92.0,
    "runtime_risks_score": 85.3,
    "test_coverage_score": 64.8,
    "code_smell_score": 71.2,
    "duplication_score": 80.0,
    "dead_code_score": 76.5,
    "consistency_score": 69.4,
    "compliance_score": 88.1,
    "critical_count": 2,
    "high_count": 8,
    "medium_count": 23,
    "low_count": 41,
    "info_count": 15,
    "total_lines_of_code": 45230,
    "test_lines_of_code": 12800,
    "structural_coverage_pct": 28.3,
    "mock_usage_pct": 12.5,
    "trigger_type": "push",
    "status": "completed",
    "created_at": "2026-03-10T08:00:00Z",
    "completed_at": "2026-03-10T08:04:32Z"
  },
  "category_breakdown": [
    {
      "category": "security",
      "count": 5,
      "critical": 1,
      "high": 2,
      "medium": 2,
      "low": 0,
      "info": 0
    },
    {
      "category": "code_smell",
      "count": 18,
      "critical": 0,
      "high": 3,
      "medium": 8,
      "low": 5,
      "info": 2
    }
  ],
  "trend_data": [
    {
      "id": "a1b2c3d4-5678-9abc-def0-111111111111",
      "overall_score": 78.5,
      "overall_grade": "B",
      "security_score": 92.0,
      "runtime_risks_score": 85.3,
      "test_coverage_score": 64.8,
      "code_smell_score": 71.2,
      "duplication_score": 80.0,
      "dead_code_score": 76.5,
      "consistency_score": 69.4,
      "compliance_score": 88.1,
      "critical_count": 2,
      "high_count": 8,
      "medium_count": 23,
      "low_count": 41,
      "info_count": 15,
      "total_lines_of_code": 45230,
      "churn_rate": 3.2,
      "refactoring_rate": 22.5,
      "convention_consistency": 82.3,
      "trigger_type": "push",
      "status": "completed",
      "created_at": "2026-03-10T08:00:00Z",
      "completed_at": "2026-03-10T08:04:32Z"
    }
  ],
  "drift_alerts": [],
  "codebase_dynamics": {
    "churn_rate": 3.2,
    "churn_change": -0.5,
    "hot_files_count": 12,
    "duplication_index": 4.8,
    "duplication_change": 0.0,
    "refactoring_rate": 22.5,
    "refactoring_interpretation": "healthy",
    "convention_consistency": 82.3,
    "convention_change": 1.2,
    "deviations_count": 7
  },
  "convention_consistency": {
    "overall_consistency": 82.3,
    "patterns": [
      {
        "name": "import_order",
        "consistency": 95.0,
        "dominant_value": "external-first",
        "total_count": 120,
        "deviation_count": 6
      }
    ]
  },
  "test_quality": {
    "structural_coverage": 28.3,
    "coverage_change": 1.5,
    "assertion_density": 2.4,
    "test_code_ratio": 0.28,
    "mock_usage_pct": 12.5
  },
  "repo_stats": [
    {
      "id": "f1a2b3c4-5678-9abc-def0-aabbccddeeff",
      "name": "corbulo",
      "full_name": "corbulo/corbulo",
      "language": "TypeScript",
      "total_loc": 45230,
      "test_loc": 12800,
      "lines_added_30d": 2340,
      "lines_deleted_30d": 890,
      "pr_count": 12
    }
  ]
}

List Assessments

Returns paginated assessment summaries for a project, ordered by creation date (newest first).

curl "https://app.corbulo.dev/api/v1/projects/b3d7f1a2-4e5c-6d8a-9b0c-1e2f3a4b5c6d/health/assessments?limit=10&offset=0" \
  -H "Authorization: Bearer ok_live_a1b2c3d4e5f6..."

{
  "items": [
    {
      "id": "a1b2c3d4-5678-9abc-def0-111111111111",
      "overall_score": 78.5,
      "overall_grade": "B",
      "trigger_type": "push",
      "status": "completed",
      "critical_count": 2,
      "high_count": 8,
      "created_at": "2026-03-10T08:00:00Z",
      "completed_at": "2026-03-10T08:04:32Z"
    },
    {
      "id": "b2c3d4e5-6789-abcd-ef01-222222222222",
      "overall_score": 77.1,
      "overall_grade": "B",
      "trigger_type": "manual",
      "status": "completed",
      "critical_count": 3,
      "high_count": 9,
      "created_at": "2026-03-08T14:30:00Z",
      "completed_at": "2026-03-08T14:34:15Z"
    }
  ],
  "total_count": 24,
  "limit": 10,
  "offset": 0
}

Get Assessment

Returns a full assessment by ID with all category scores and metrics.

curl "https://app.corbulo.dev/api/v1/projects/b3d7f1a2-4e5c-6d8a-9b0c-1e2f3a4b5c6d/health/assessments/a1b2c3d4-5678-9abc-def0-111111111111" \
  -H "Authorization: Bearer ok_live_a1b2c3d4e5f6..."

{
  "id": "a1b2c3d4-5678-9abc-def0-111111111111",
  "project_id": "b3d7f1a2-4e5c-6d8a-9b0c-1e2f3a4b5c6d",
  "overall_score": 78.5,
  "overall_grade": "B",
  "security_score": 92.0,
  "runtime_risks_score": 85.3,
  "test_coverage_score": 64.8,
  "code_smell_score": 71.2,
  "duplication_score": 80.0,
  "dead_code_score": 76.5,
  "consistency_score": 69.4,
  "compliance_score": 88.1,
  "critical_count": 2,
  "high_count": 8,
  "medium_count": 23,
  "low_count": 41,
  "info_count": 15,
  "total_lines_of_code": 45230,
  "test_lines_of_code": 12800,
  "actual_coverage_percent": null,
  "structural_coverage_pct": 28.3,
  "mock_usage_pct": 12.5,
  "trigger_type": "push",
  "status": "completed",
  "created_at": "2026-03-10T08:00:00Z",
  "completed_at": "2026-03-10T08:04:32Z"
}

Assessment Fields

Field	Type	Description
`overall_score`	number	Weighted average of all category scores (0-100)
`overall_grade`	string	Letter grade: `A`, `B`, `C`, `D`, or `F`
`*_score`	number	Per-category scores (0-100)
`critical_count` … `info_count`	integer	Issue counts by severity
`total_lines_of_code`	integer	Total lines of code in the project
`test_lines_of_code`	integer	Lines of test code
`structural_coverage_pct`	number	Structural test coverage percentage
`trigger_type`	string	`manual`, `push`, `pr_merge`, or `scheduled`
`status`	string	`pending`, `running`, `completed`, or `failed`

Trigger Assessment

Triggers a new health assessment. The assessment runs asynchronously.

curl -X POST "https://app.corbulo.dev/api/v1/projects/b3d7f1a2-4e5c-6d8a-9b0c-1e2f3a4b5c6d/health/trigger" \
  -H "Authorization: Bearer ok_live_a1b2c3d4e5f6..."

{
  "status": "queued",
  "assessment_id": "c3d4e5f6-7890-abcd-ef01-333333333333",
  "workflow_id": "health-assessment-b3d7f1a2-c3d4e5f6"
}

List Drift Alerts

Returns drift alerts for a project. Drift alerts are generated when health scores change significantly between assessments.

curl "https://app.corbulo.dev/api/v1/projects/b3d7f1a2-4e5c-6d8a-9b0c-1e2f3a4b5c6d/health/drift-alerts?limit=20&offset=0" \
  -H "Authorization: Bearer ok_live_a1b2c3d4e5f6..."

[
  {
    "id": "d4e5f6a7-8901-2345-6789-444444444444",
    "project_id": "b3d7f1a2-4e5c-6d8a-9b0c-1e2f3a4b5c6d",
    "assessment_id": "a1b2c3d4-5678-9abc-def0-111111111111",
    "drift_type": "score",
    "category": "test_coverage",
    "previous_value": 70.2,
    "current_value": 64.8,
    "change": -5.4,
    "message": "Test coverage score dropped by 5.4 points",
    "affected_files": ["src/services/auth.ts", "src/services/billing.ts"],
    "detected_at": "2026-03-10T08:04:32Z",
    "dismissed": false
  }
]

Drift Alert Fields

Field	Type	Description
`drift_type`	string	`score`, `coverage`, `convention`, or `churn`
`category`	string	The health category affected
`previous_value`	number	Value from the previous assessment
`current_value`	number	Value from the current assessment
`change`	number	Delta between assessments

Dismiss Drift Alert

Dismisses a drift alert so it no longer appears in active alerts.

curl -X POST "https://app.corbulo.dev/api/v1/projects/b3d7f1a2-4e5c-6d8a-9b0c-1e2f3a4b5c6d/health/drift-alerts/d4e5f6a7-8901-2345-6789-444444444444/dismiss" \
  -H "Authorization: Bearer ok_live_a1b2c3d4e5f6..."

{
  "status": "dismissed"
}

List Issues

Returns analysis issues for a project with optional filters. Issues are findings from static analyzers, AI analysis, graph rules, and convention checks.

curl "https://app.corbulo.dev/api/v1/projects/b3d7f1a2-4e5c-6d8a-9b0c-1e2f3a4b5c6d/analysis/issues?severity=critical&category=security&limit=50&offset=0" \
  -H "Authorization: Bearer ok_live_a1b2c3d4e5f6..."

{
  "issues": [
    {
      "id": "e5f6a7b8-9012-3456-7890-555555555555",
      "source": "llm_agent",
      "severity": "critical",
      "file_path": "src/auth/token.ts",
      "file_group": "src/auth",
      "anchor": {
        "line_start": 42,
        "line_end": 48,
        "code_snippet": "const token = jwt.sign(payload, SECRET_KEY)",
        "validated": true
      },
      "category": "security",
      "title": "Hardcoded secret key in JWT signing",
      "description": "The JWT signing key is hardcoded as a string constant rather than loaded from environment configuration.",
      "why_it_matters": "Hardcoded secrets are exposed in source control and cannot be rotated without a code change and redeployment.",
      "suggested_action": "Move the secret key to an environment variable and load it at startup via configuration.",
      "rule_id": "SEC001",
      "analyzer_name": "security-agent",
      "confidence": 95,
      "auto_fixable": false,
      "is_new": false,
      "is_dismissed": false,
      "context_type": "health_assessment",
      "context_id": "a1b2c3d4-5678-9abc-def0-111111111111",
      "project_id": "b3d7f1a2-4e5c-6d8a-9b0c-1e2f3a4b5c6d",
      "repository_id": "f1a2b3c4-5678-9abc-def0-aabbccddeeff",
      "created_at": "2026-03-08T14:32:00Z"
    }
  ],
  "total": 5
}

Query Parameters

Parameter	Type	Description
`severity`	string	Filter by severity: `critical`, `high`, `medium`, `low`, `info`
`severities`	string	Comma-separated list of severities (OR filter)
`category`	string	Filter by category: `security`, `runtime`, `testing`, `code_smell`, `dead_code`, `duplication`, `consistency`, `compliance`
`source`	string	Filter by source: `static_analyzer`, `llm_agent`, `graph_rule`, `convention`, `architecture`
`is_dismissed`	boolean	Filter dismissed/active issues
`context_type`	string	Filter by analysis context: `pr_analysis`, `health_assessment`, `architecture_review`, `push`
`context_id`	string	Filter by specific analysis run context
`sort_by`	string	Sort by: `severity`, `file_path`, `category`, `created_at`
`limit`	integer	Items per page	50
`offset`	integer	Number of items to skip	0

Get Issue Statistics

Returns aggregate issue counts for a project, grouped by category, severity, and source.

curl "https://app.corbulo.dev/api/v1/projects/b3d7f1a2-4e5c-6d8a-9b0c-1e2f3a4b5c6d/analysis/issues/stats" \
  -H "Authorization: Bearer ok_live_a1b2c3d4e5f6..."

{
  "by_category": {
    "security": 5,
    "runtime": 3,
    "testing": 12,
    "code_smell": 18,
    "dead_code": 8,
    "duplication": 6,
    "consistency": 7,
    "compliance": 2
  },
  "by_severity": {
    "critical": 2,
    "high": 8,
    "medium": 23,
    "low": 21,
    "info": 7
  },
  "by_source": {
    "llm_agent": 35,
    "static_analyzer": 18,
    "convention": 5,
    "graph_rule": 3
  },
  "total": 61,
  "dismissed": 4
}

Dismiss Issue

Dismisses an issue with an action and optional reason. Creates a dismiss rule to suppress future matches.

curl -X POST "https://app.corbulo.dev/api/v1/projects/b3d7f1a2-4e5c-6d8a-9b0c-1e2f3a4b5c6d/analysis/issues/e5f6a7b8-9012-3456-7890-555555555555/dismiss" \
  -H "Authorization: Bearer ok_live_a1b2c3d4e5f6..." \
  -H "Content-Type: application/json" \
  -d '{
    "action": "false_positive",
    "reason": "This key is loaded from env in production; the test fixture is fine."
  }'

{
  "status": "dismissed"
}

Request Body

Field	Type	Required	Description
`action`	string	no	`dismiss`, `false_positive`, or `wont_fix`. Defaults to `dismiss`.
`reason`	string	no	Human-readable reason for dismissing

Restore Issue

Restores a previously dismissed issue back to active status.

curl -X POST "https://app.corbulo.dev/api/v1/projects/b3d7f1a2-4e5c-6d8a-9b0c-1e2f3a4b5c6d/analysis/issues/e5f6a7b8-9012-3456-7890-555555555555/restore" \
  -H "Authorization: Bearer ok_live_a1b2c3d4e5f6..."

{
  "status": "restored"
}

List Dismiss Rules

Returns all dismiss rules configured for a project. Dismiss rules automatically suppress matching issues.

curl "https://app.corbulo.dev/api/v1/projects/b3d7f1a2-4e5c-6d8a-9b0c-1e2f3a4b5c6d/analysis/dismiss-rules" \
  -H "Authorization: Bearer ok_live_a1b2c3d4e5f6..."

[
  {
    "id": "f6a7b8c9-0123-4567-8901-666666666666",
    "source_type": "static_analyzer",
    "rule_pattern": "no-unused-vars",
    "secondary_pattern": null,
    "scope": "file",
    "file_path": "src/generated/**",
    "action": "wont_fix",
    "reason": "Generated code has expected unused variables",
    "match_count": 14,
    "created_at": "2026-02-20T10:00:00Z"
  }
]

Create Dismiss Rule

Creates a new dismiss rule that automatically suppresses matching issues.

curl -X POST "https://app.corbulo.dev/api/v1/projects/b3d7f1a2-4e5c-6d8a-9b0c-1e2f3a4b5c6d/analysis/dismiss-rules" \
  -H "Authorization: Bearer ok_live_a1b2c3d4e5f6..." \
  -H "Content-Type: application/json" \
  -d '{
    "rule_pattern": "no-unused-vars",
    "source_type": "static_analyzer",
    "scope": "file",
    "file_path": "src/generated/**",
    "action": "wont_fix",
    "reason": "Generated code has expected unused variables"
  }'

{
  "id": "a7b8c9d0-1234-5678-9012-777777777777",
  "source_type": "static_analyzer",
  "rule_pattern": "no-unused-vars",
  "secondary_pattern": null,
  "scope": "file",
  "file_path": "src/generated/**",
  "action": "wont_fix",
  "reason": "Generated code has expected unused variables",
  "match_count": 0,
  "created_at": "2026-03-10T12:30:00Z"
}

Request Body

Field	Type	Required	Description
`rule_pattern`	string	yes	Pattern to match against issue rule IDs or titles
`source_type`	string	no	Restrict to a specific source: `static_analyzer`, `llm_agent`, `graph_rule`, `convention`, `architecture`
`secondary_pattern`	string	no	Additional pattern for finer matching
`scope`	string	no	`global`, `project`, or `file`. Defaults to `global`.
`file_path`	string	no	File path or glob pattern (required when scope is `file`)
`action`	string	no	`dismiss`, `false_positive`, or `wont_fix`. Defaults to `dismiss`.
`reason`	string	no	Human-readable reason

Delete Dismiss Rule

Removes a dismiss rule. Previously suppressed issues will reappear as active.

curl -X DELETE "https://app.corbulo.dev/api/v1/projects/b3d7f1a2-4e5c-6d8a-9b0c-1e2f3a4b5c6d/analysis/dismiss-rules/f6a7b8c9-0123-4567-8901-666666666666" \
  -H "Authorization: Bearer ok_live_a1b2c3d4e5f6..."

Returns 204 No Content on success.

List Health Categories

Returns metadata for all 8 health scoring categories.

curl "https://app.corbulo.dev/api/v1/projects/b3d7f1a2-4e5c-6d8a-9b0c-1e2f3a4b5c6d/health/categories" \
  -H "Authorization: Bearer ok_live_a1b2c3d4e5f6..."

[
  { "name": "Security", "key": "security", "icon": "security", "color": "red" },
  { "name": "Runtime Risks", "key": "runtime_risks", "icon": "bolt", "color": "red" },
  { "name": "Test Coverage", "key": "test_coverage", "icon": "rule", "color": "purple" },
  { "name": "Code Smells", "key": "code_smell", "icon": "code_off", "color": "amber" },
  { "name": "Duplication", "key": "duplication", "icon": "content_copy", "color": "orange" },
  { "name": "Dead Code", "key": "dead_code", "icon": "delete_sweep", "color": "slate" },
  { "name": "Codebase Consistency", "key": "consistency", "icon": "sync_problem", "color": "indigo" },
  { "name": "Compliance", "key": "compliance", "icon": "gavel", "color": "blue" }
]

​Code Health API

​Get Health Dashboard

​List Assessments

​Get Assessment

​Assessment Fields

​Trigger Assessment

​List Drift Alerts

​Drift Alert Fields

​Dismiss Drift Alert

​List Issues

​Query Parameters

​Get Issue Statistics

​Dismiss Issue

​Request Body

​Restore Issue

​List Dismiss Rules

​Create Dismiss Rule

​Request Body

​Delete Dismiss Rule

​List Health Categories

Code Health API

Get Health Dashboard

List Assessments

Get Assessment

Assessment Fields

Trigger Assessment

List Drift Alerts

Drift Alert Fields

Dismiss Drift Alert

List Issues

Query Parameters

Get Issue Statistics

Dismiss Issue

Request Body

Restore Issue

List Dismiss Rules

Create Dismiss Rule

Request Body

Delete Dismiss Rule

List Health Categories