Skip to main content
POST
Start Code Scan

Permissions

Requires a service user or personal access token with the UseAccountCodeScans permission at the enterprise level.

Behavior

Enqueues a new code scan for the given repository (repo_name) or repositories (repos) in the given 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).

Request fields

Provide exactly one of repo_name or repos.
  • repo_name: 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.
  • repos: repositories covered by one multi-repo scan, as a list of objects with repo_name and an optional host (up to 200). The first entry is the scan’s primary repository.
  • 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.
  • effort: normal (default) uses lower model reasoning effort with larger investigation batches; deep runs the full pipeline.
  • interactive: when true, the scan pauses in awaiting_user_input for user review between threat modeling and investigation. Defaults to false. Only security scans support interactive review; other scan types run unattended.
  • platform: where the scan’s sessions run, either a platform label configured for the organization (for example linux, windows, or macos) or the name of an outpost pool, case-insensitive. Platforms take priority when a name matches both. Defaults to the organization default.

Errors

  • 400 when scan_type conflicts with the profile, a non-security scan_type is given without a profile, or platform does not match a configured platform label or outpost pool (the error body lists the available values).
  • 403 when the organization is restricted to ingestion-only scans and no ingest-mode profile is given.
  • 404 when the organization, repository, or profile is not visible to the enterprise account.
  • 409 when the organization’s scan backlog is at capacity. Retry later.
  • 422 when both or neither of repo_name and repos are provided, or repos is empty.

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.

commit_sha
string | null

Commit to check out before scanning.

effort
enum<string> | null

Scan effort: 'normal' (default) uses lower model reasoning effort with larger investigation batches; 'deep' runs the full pipeline.

Available options:
normal,
deep
host
string | null

Git host of the repository, if known.

interactive
boolean
default:false

When true, the scan pauses for user review between threat modeling and investigation.

platform
string | null

Where the scan's sessions run: a platform label configured for the organization (e.g. 'linux', 'windows', 'macos') or the name of an outpost (BYOB) pool, case-insensitive; platforms take priority when a name matches both. Omitted means the organization default. Unrecognized values are rejected with a 400 whose error body lists the available platform labels and outpost pool names.

Maximum string length: 128
profile_id
string | null

Scan profile to apply to the scan.

repo_name
string | null

Full name of the repository to scan. Provide exactly one of repo_name or repos.

repos
ScanRepoRequest · object[] | null

Repositories covered by one scan; the first entry is the scan's primary repository. Provide exactly one of repo_name or repos.

Maximum array length: 200
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,
cleanup,
telemetry,
accessibility,
compliance,
general,
migration-docs

Response

Successful Response

A single code scan.

created_at
integer
required

When the scan was created (unix seconds).

effort
enum<string>
required

Scan effort: 'normal' uses lower model reasoning effort with larger investigation batches; 'deep' runs the full pipeline.

Available options:
normal,
deep
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,
cleanup,
telemetry,
accessibility,
compliance,
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
url
string
required

URL of the scan's page in the Devin webapp.

outpost_pool_id
string | null

Outpost pool the scan's sessions run on, if one is set.

platform
string | null

Hosted platform label the scan's sessions run on. Null when the scan runs on an outpost pool or the organization default.

repo_full_name
string | null

Host-qualified identity of the primary repository (e.g. github.com/org/repo). Null for Perforce depots, which have no git host.