Trigger Repository Scan

Initiate a security scan on a repository

POST /api/repos/{id}/scan

Trigger Repository Scan

cURL

curl --request POST \
  --url https://api.example.com/api/repos/{id}/scan

200

{
  "success": true,
  "data": {
    "id": "<string>",
    "repo_id": "<string>",
    "scan_type": "<string>",
    "status": "<string>",
    "triggered_by": "<string>",
    "commit_sha": "<string>",
    "base_commit_sha": "<string>",
    "parent_scan_id": "<string>",
    "finding_count": 123,
    "critical_count": 123,
    "high_count": 123,
    "medium_count": 123,
    "low_count": 123,
    "started_at": {},
    "completed_at": {},
    "error_message": "<string>",
    "created_at": {},
    "updated_at": {}
  },
  "error": {
    "success": true,
    "code": 123,
    "message": "<string>"
  }
}

Authentication

This endpoint requires authentication. Include your session token in the request cookies or headers.

Path Parameters

id · uuid · required

The unique identifier of the repository to scan.

Request Details

This endpoint does not accept a request body. The scan will be performed using the repository’s configured source and default branch.

Scan Process

When triggered, the scan will:

1. Create a new scan record with status queued
2. Determine the appropriate AI model and provider for the user
3. Either queue a background job (in production) or start an inline scan (in development)
4. Progress through multiple stages: ingesting, modeling, static analysis, hunting, validating, and reporting
5. Generate findings for security vulnerabilities, anti-patterns, and potential issues

Response

success · boolean

Indicates whether the scan was successfully initiated.

data · object

The created scan object.

Show Scan Object

id · uuid

Unique identifier for the scan.

repo_id · uuid

ID of the repository being scanned.

scan_type · string

Type of scan performed. Currently always full.

status · string

Current status of the scan. Initial value is queued. Possible values:

• queued - Waiting to start
• ingesting - Fetching and processing code
• ingested - Code successfully loaded
• modeling - Creating threat model
• modeled - Threat model complete
• static_analysis - Running static analysis
• hunting - AI-powered vulnerability hunting
• hunted - Hunting complete
• validating - Validating findings
• validated - Validation complete
• reporting - Generating report
• completed - Scan finished successfully
• failed - Scan encountered an error
• cancelled - Scan was cancelled

triggered_by · uuid

ID of the user who triggered the scan.

commit_sha · string

Git commit SHA being scanned, if applicable.

base_commit_sha · string

Base commit SHA for differential scans.

parent_scan_id · uuid

ID of the parent scan for incremental scans.

finding_count · integer

Total number of findings. Initially 0.

critical_count · integer

Number of critical severity findings. Initially 0.

high_count · integer

Number of high severity findings. Initially 0.

medium_count · integer

Number of medium severity findings. Initially 0.

low_count · integer

Number of low severity findings. Initially 0.

started_at · datetime

Timestamp when the scan actually started processing.

completed_at · datetime

Timestamp when the scan finished.

error_message · string

Error message if the scan failed.

created_at · datetime

Timestamp when the scan was created.

updated_at · datetime

Timestamp when the scan was last updated.

Example Request

curl -X POST https://api.heimdall.example.com/api/repos/01936d2f-8c4e-7890-b123-456789abcdef/scan \
  -H "Cookie: session=your_session_token"

Example Response

{
  "success": true,
  "data": {
    "id": "01936d30-abcd-1234-5678-90abcdef1234",
    "repo_id": "01936d2f-8c4e-7890-b123-456789abcdef",
    "scan_type": "full",
    "status": "queued",
    "triggered_by": "01936d2e-1234-5678-9abc-def012345678",
    "commit_sha": null,
    "base_commit_sha": null,
    "parent_scan_id": null,
    "finding_count": 0,
    "critical_count": 0,
    "high_count": 0,
    "medium_count": 0,
    "low_count": 0,
    "started_at": null,
    "completed_at": null,
    "error_message": null,
    "created_at": "2026-03-12T16:20:00Z",
    "updated_at": "2026-03-12T16:20:00Z"
  }
}

Error Responses

error · object

Error information when the request fails.

Show Error Object

success · boolean

Always false for error responses.

code · integer

HTTP status code.

message · string

Error message describing what went wrong.

401 Unauthorized

Returned when authentication credentials are missing or invalid.

{
  "success": false,
  "code": 401,
  "message": "Authentication required"
}

404 Not Found

Returned when the repository with the specified ID does not exist.

{
  "success": false,
  "code": 404,
  "message": "Repo '01936d2f-8c4e-7890-b123-456789abcdef' not found"
}

500 Internal Server Error

Returned when the server encounters an error creating the scan.

{
  "success": false,
  "code": 500,
  "message": "Failed to create scan: database connection error"
}

503 Service Unavailable

Returned when the AI service is not available or not configured for the user.

{
  "success": false,
  "code": 503,
  "message": "AI service unavailable. Please configure your API keys."
}

Status Code

Successful scan creation returns HTTP status code 202 Accepted, indicating that the request has been accepted for processing but the scan is not yet complete.

Notes

• Scans are asynchronous operations. Use the returned scan_id to poll the scan status or subscribe to server-sent events (SSE) for real-time updates.
• The scan will use the AI model configured for the repository owner’s account.
• For OAuth-connected repositories (GitHub/GitLab), the scan will use stored credentials to access the repository.
• If automatic issue creation is enabled for the repository, issues will be created based on the configured severity threshold.
• If you’re using HTMX-based requests (with HX-Request header), the response will include an HX-Redirect header pointing to /scans/{scan_id}.