Skip to content
CodeCleared Docs
AppFrançais
Published

Last reviewed: 2026-09-08

Scans API

Create CodeCleared scans with repository UUIDs and commit hashes, wait safely for completion, and handle project units, credits, and timeouts.

Purpose

Use this API to create an authorized scan for a connected repository and observe its completion. Authenticate every request with Authorization: Bearer <service-token>.

Prerequisites

You need an API credential/service token with access to the organization, a connected repository, and an eligible credit pool. API access is typically Team or above.

Steps

  1. Resolve the human repository name: GET /v1/repositories/resolve?fullName=owner/repo.
  2. Read the returned repository UUID.
  3. Create the scan with POST /v1/scans and repositoryId plus commitHash.
  4. Optionally pass branch, projectUnitId, or scanTypes.
  5. Wait with GET /v1/scans/:id/wait?timeout=300&interval=10.
{ "repositoryId": "repository-uuid", "commitHash": "full-commit-hash", "branch": "main", "scanTypes": ["sca"] }

Optionally upload a CI-built artifact (CLI / BYOT): XOR lockfile { "path", "content" } or sbom (CycloneDX object). When present, sourceTrigger is cli, dedup by commit is skipped, and projectUnitId is required. Body ≤ 10 MB. Without artifact, behavior matches the classic API path (sourceTrigger=api).

{ "repositoryId": "repository-uuid", "projectUnitId": "pu-uuid", "commitHash": "full-commit-hash", "lockfile": { "path": "package-lock.json", "content": "..." } }

Business rules

Scan creation requires the UUID repositoryId and commitHash, not commitSha; do not send fullName. The wait endpoint defaults to 300 seconds and accepts a maximum timeout of 600 seconds. A 402 means credit, plan entitlement, or a MAU license (seat_license_required) is unavailable, not that JSON is malformed. Artifact uploads use the same credit gate.

Scenarios & edge cases

Resolve fails: check the exact owner/repo and repository connection. Wait times out: keep the scan ID, query later, and do not create duplicate work just because your client stopped waiting. Wrong project unit: verify its repository ownership before submitting.
Partial scope (scanTypes): allowed values sbom, sca, license, dependency-advisor, secrets, sast, all. Specify only what your workflow needs (e.g. ["sca"] for Maven BYOT). Mismatched types for a unit type are rejected or skipped.
Wait summary: keys are scoped to requested types — e.g. scanTypes: ["sca"] returns only vulnerabilities (no empty secrets / licenses). Full / omitted scanTypes keeps the classic three-key shape. Includes summary.severityThreshold — the org apiGateSeverityThreshold used for this verdict.
Wait verdict (CI gate): PASS / FAIL is not “any finding”. Failures for vulns / secrets use org apiGateSeverityThreshold (default critical; Settings → Scan defaults / Onboarding; org only — not a repo override). FAIL when at least one vulnerability or secret is ≥ that threshold, or a license is non-compliant (within the requested scanTypes dimensions). This is not Quality Gates and is separate from PR prCheckSeverityThreshold. Reasons: keep critical_vulnerabilities_found / critical_secrets_found when the threshold is critical; otherwise vulnerabilities_above_threshold / secrets_above_threshold; licenses stay non_compliant_licenses_found. Findings below the threshold still appear in summary with verdict: PASS and reason: no_issues_found (no gate issues). Job failed / cancelled → ERROR. Same rule for CLI --wait and MCP wait.
GET /v1/scans/:id (status): status + project units only — no verdict/summary (use /wait for the gate payload).
Inaccessible commitHash: Temporal identifyCommit fails with errorCode: branch_or_commit_not_found; the orchestrator ScanJob is marked failed (via workflow + updateScanJobActivity) so /wait returns ERROR instead of timing out.
BYOT lockfile.path: must be relative (no .., no absolute paths). Body ≤ 10 MB. XOR lockfile | sbom; artifact requires projectUnitId.
Scan activity failure (credits, entitlement, scanner): same path — orchestrator becomes failed with a stable errorCode; leftover BYOT lockfileContent is stripped on failed update.

Limits

Never place a service token in a URL or CI output. Bound wait time to 600 seconds; use asynchronous handling for longer business workflows.

Common errors

  • Sending commitSha instead of commitHash.
  • Sending a repository name instead of repositoryId.
  • Treating 401/403 as 402; the former concerns authentication or scope.

Failure status (error / errorCode)

GET /v1/scans/:id (and wait responses) include per-project-unit error and errorCode when a unit failed. Optional top-level errorCode mirrors the first failed unit. Stable codes include pat_required, repo_access, rate_limit, insufficient_credits, payment_failed, sast_addon_required, entitlement_denied, lockfile_not_found, branch_or_commit_not_found, workflow_timeout, and system_error. Wait reason stays scan_failed for compatibility; use errorCode for actionable detail. See Scan failures.

Links