Skip to main content
POST
Start Code Scan

Permissions

Requires a service user or personal access token with the UseCodeScans permission at the organization level.

Behavior

Enqueues a new code scan for repo_name in the organization. The scan is launched asynchronously by the scan dispatcher; the response is the scan record with an initial status of waiting or pending. Poll List Code Scans to track progress, and List Code Scan Findings (filtered by scan_id) to read results once the scan reaches completed. The scan is attributed to the calling principal (the service user or PAT that made the request). The enterprise-scoped equivalent is Start Code Scan (Enterprise).

Request fields

  • repo_name (required): full repository name, e.g. owner/repo. The repository must already be accessible through the organization’s Git integration.
  • host: Git host of the repository, if it cannot be inferred.
  • profile_id: a scan profile to apply. Use Start Ingestion Scan for ingest-mode profiles.
  • scan_type: type of scan to run. Must match the profile’s scan type when profile_id is given. Defaults to the profile’s type, or security for profile-less scans. Non-security scan types require a profile.
  • commit_sha: commit to check out before scanning. Defaults to the repository’s default branch head.

Errors

  • 400 when scan_type conflicts with the profile, or a non-security scan_type is given without a profile.
  • 403 when the organization is restricted to ingestion-only scans and no ingest-mode profile is given.
  • 404 when the repository or profile is not visible to the organization.
  • 409 when the organization’s scan backlog is at capacity. Retry later.

Authorizations

Authorization
string
header
required

Service User credential (prefix: cog_)

Path Parameters

org_id
string
required

Organization ID (prefix: org-)

Example:

"org-abc123def456"

Body

application/json

Request body for starting a new code scan.

repo_name
string
required

Full name of the repository to scan.

commit_sha
string | null

Commit to check out before scanning.

host
string | null

Git host of the repository, if known.

profile_id
string | null

Scan profile to apply to the scan.

scan_type
enum<string> | null

Type of scan to run. Must match the profile's scan type when a profile is given; defaults to the profile's type, or 'security' for profile-less scans. Non-security types require a profile and are rejected without one.

Available options:
security,
performance,
db-queries,
test-coverage,
dead-code,
code-quality,
telemetry,
accessibility,
general,
migration-docs

Response

Successful Response

A single code scan.

created_at
integer
required

When the scan was created (unix seconds).

host
string | null
required

Git host of the repository, if known.

org_id
string
required

Organization the scan belongs to.

profile
CodeScanProfileResponse · object | null
required

Profile the scan ran under, if any.

repo_name
string
required

Primary repository of the scan. Multi-repo scans cover additional repositories not listed here.

scan_id
string
required

Unique identifier for the scan.

scan_type
enum<string>
required

Type of scan, stamped at creation.

Available options:
security,
performance,
db-queries,
test-coverage,
dead-code,
code-quality,
telemetry,
accessibility,
general,
migration-docs
status
enum<string>
required

Scan status: waiting, pending, running, awaiting_user_input, completed, failed, or cancelled.

Available options:
waiting,
pending,
running,
awaiting_user_input,
completed,
failed,
cancelled