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 the given repository (repo_name) or repositories (repos) 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

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 repository or profile is not visible to the organization.
  • 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.

new_budget
NewScanBudget · object | null

Give the scan its own ACU budget. Requires the ManageAccountServiceUsers and ManageAcuLimits permissions.

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.