> ## Documentation Index
> Fetch the complete documentation index at: https://docs.octokraft.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Code Health API
> Access health scores, assessments, drift alerts, and analysis issues
# 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.
```bash Request theme={null}
curl "https://app.corbulo.dev/api/v1/projects/b3d7f1a2-4e5c-6d8a-9b0c-1e2f3a4b5c6d/health" \
-H "Authorization: Bearer ok_live_a1b2c3d4e5f6..."
```
```json Response theme={null}
{
"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).
```bash Request theme={null}
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..."
```
```json Response theme={null}
{
"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.
```bash Request theme={null}
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..."
```
```json Response theme={null}
{
"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.
```bash Request theme={null}
curl -X POST "https://app.corbulo.dev/api/v1/projects/b3d7f1a2-4e5c-6d8a-9b0c-1e2f3a4b5c6d/health/trigger" \
-H "Authorization: Bearer ok_live_a1b2c3d4e5f6..."
```
```json Response theme={null}
{
"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.
```bash Request theme={null}
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..."
```
```json Response theme={null}
[
{
"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.
```bash Request theme={null}
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..."
```
```json Response theme={null}
{
"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.
```bash Request theme={null}
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..."
```
```json Response theme={null}
{
"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.
```bash Request theme={null}
curl "https://app.corbulo.dev/api/v1/projects/b3d7f1a2-4e5c-6d8a-9b0c-1e2f3a4b5c6d/analysis/issues/stats" \
-H "Authorization: Bearer ok_live_a1b2c3d4e5f6..."
```
```json Response theme={null}
{
"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.
```bash Request theme={null}
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."
}'
```
```json Response theme={null}
{
"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.
```bash Request theme={null}
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..."
```
```json Response theme={null}
{
"status": "restored"
}
```
***
## List Dismiss Rules
Returns all dismiss rules configured for a project. Dismiss rules automatically suppress matching issues.
```bash Request theme={null}
curl "https://app.corbulo.dev/api/v1/projects/b3d7f1a2-4e5c-6d8a-9b0c-1e2f3a4b5c6d/analysis/dismiss-rules" \
-H "Authorization: Bearer ok_live_a1b2c3d4e5f6..."
```
```json Response theme={null}
[
{
"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.
```bash Request theme={null}
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"
}'
```
```json Response (201 Created) theme={null}
{
"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.
```bash Request theme={null}
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.
```bash Request theme={null}
curl "https://app.corbulo.dev/api/v1/projects/b3d7f1a2-4e5c-6d8a-9b0c-1e2f3a4b5c6d/health/categories" \
-H "Authorization: Bearer ok_live_a1b2c3d4e5f6..."
```
```json Response theme={null}
[
{ "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" }
]
```