Skip to main content
POST
/
api
/
repos
/
{id}
/
scan
Trigger Repository Scan
curl --request POST \
  --url https://api.example.com/api/repos/{id}/scan
{
  "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.

​
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.

​
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}.

Build docs developers (and LLMs) love

Get started for freeTalk to us