On-Demand Code Scans Beta

On-Demand Code Scans are currently in beta. The API is available for early CLI, IDE, pre-commit, and custom integration workflows, but behavior, limits, and response fields may change before general availability.

Overview

On-Demand Code Scans let you submit small units of code to ZeroPath for security analysis without starting a full repository scan. Use them when you want fast feedback from a CLI, IDE integration, pre-commit hook, CI job, or custom tool. You can submit:

A Git diff
A single file
Multiple files
One or more code snippets

The scan runs asynchronously. Submit a job, poll its status, then fetch the results.

On-Demand Code Scans are not full repository scans. They analyze only the code you submit. Results are returned through the async code scan API and expire after 7 days.

Target Modes

Every scan request includes a target. The target controls whether ZeroPath uses repository context or treats the submitted code as standalone.

Target	Use when
`auto`	Recommended for CLIs, IDEs, pre-commit hooks, and custom developer tools. ZeroPath uses the submitted Git remote URL to find a linked repository when exactly one accessible match exists. Otherwise, the scan runs standalone.
`repository`	Your integration already knows the ZeroPath `repositoryId` and should require linked repository context.
`standalone`	You explicitly want to scan submitted code without linked ZeroPath repository context.

When a repository is resolved, ZeroPath can use persisted repository, application, and threat-model context to improve analysis. Standalone scans use only the submitted code, optional target metadata, and optional supplemental context.

Submit a Scan

Call POST /api/v2/async-code-scans/submit with your code input and target.

curl -X POST https://zeropath.com/api/v2/async-code-scans/submit \
  -H "Content-Type: application/json" \
  -H "X-ZeroPath-API-Token-Id: $ZEROPATH_API_TOKEN_ID" \
  -H "X-ZeroPath-API-Token-Secret: $ZEROPATH_API_TOKEN_SECRET" \
  -d '{
    "target": {
      "kind": "auto",
      "remoteUrl": "https://github.com/acme/app.git",
      "label": "app"
    },
    "input": {
      "kind": "diff",
      "diff": "diff --git a/api.ts b/api.ts\n..."
    },
    "metadata": {
      "caller": "cli",
      "baseRef": "main",
      "headRef": "feature/auth-check"
    }
  }'

Successful submissions return 202 Accepted:

{
  "jobId": "7f3f7fd5-7ad0-4e94-99c8-2a78d98e6316",
  "status": "queued",
  "createdAt": "2026-05-17T18:30:00.000Z"
}

Poll Status

Call POST /api/v2/async-code-scans/status with the returned jobId.

curl -X POST https://zeropath.com/api/v2/async-code-scans/status \
  -H "Content-Type: application/json" \
  -H "X-ZeroPath-API-Token-Id: $ZEROPATH_API_TOKEN_ID" \
  -H "X-ZeroPath-API-Token-Secret: $ZEROPATH_API_TOKEN_SECRET" \
  -d '{"jobId": "7f3f7fd5-7ad0-4e94-99c8-2a78d98e6316"}'

The public statuses are:

queued
running
completed
failed

Repository-backed jobs require repository view access. Standalone jobs can be viewed only by the same submitting API token or same submitting user.

Fetch Results

Call POST /api/v2/async-code-scans/results after the job completes.

curl -X POST https://zeropath.com/api/v2/async-code-scans/results \
  -H "Content-Type: application/json" \
  -H "X-ZeroPath-API-Token-Id: $ZEROPATH_API_TOKEN_ID" \
  -H "X-ZeroPath-API-Token-Secret: $ZEROPATH_API_TOKEN_SECRET" \
  -d '{"jobId": "7f3f7fd5-7ad0-4e94-99c8-2a78d98e6316"}'

Results include structured vulnerabilities with file location, severity, confidence, CWE identifiers, and an optional fix:

{
  "jobId": "7f3f7fd5-7ad0-4e94-99c8-2a78d98e6316",
  "status": "completed",
  "codeScanId": null,
  "result": {
    "vulnerabilities": [
      {
        "id": "1e32c0db-0e54-4bf8-8e41-d70ac2b8d72b",
        "title": "Missing authorization check",
        "description": "The submitted handler updates another user's account without verifying ownership.",
        "file": "api.ts",
        "startLine": 42,
        "endLine": 48,
        "vulnerabilityClass": "Broken Access Control",
        "severity": "high",
        "confidence": 8.5,
        "language": "typescript",
        "cwes": ["CWE-862"],
        "fix": {
          "description": "Require the authenticated user to own the account before applying the update."
        }
      }
    ]
  },
  "error": null
}

On-Demand Code Scan results are temporary and are meant to be consumed from the API response for the submitted job.

Input Shapes

Use exactly one input shape per request.

Diff

{
  "kind": "diff",
  "diff": "diff --git a/api.ts b/api.ts\n..."
}

File

{
  "kind": "file",
  "path": "src/api.ts",
  "language": "typescript",
  "content": "export async function handler(req) { ... }"
}

Files

{
  "kind": "files",
  "files": [
    {
      "path": "src/api.ts",
      "language": "typescript",
      "content": "..."
    }
  ]
}

Snippets

{
  "kind": "snippets",
  "snippets": [
    {
      "label": "Express route",
      "language": "typescript",
      "content": "app.post('/users/:id', ...)"
    }
  ]
}

Supplemental Context

Use additionalContext for background information that can help the scanner interpret the submitted code.

{
  "additionalContext": "This route is reachable by authenticated tenant admins only."
}

ZeroPath treats supplemental context as untrusted background information, not as scanner instructions.

CLI Usage

The ZeroPath CLI includes scan-code for On-Demand Code Scans.

# Scan the current Git working-tree diff
zeropath scan-code --diff

# Scan staged changes
zeropath scan-code --staged

# Scan one source file
zeropath scan-code --file src/api.ts

# Scan multiple source files
zeropath scan-code --files src/api.ts src/auth.ts

# Scan a snippet
zeropath scan-code --snippet "const token = req.query.token"

# Read a snippet from stdin
cat route.ts | zeropath scan-code --stdin --language typescript

By default, the CLI uses target.kind = "auto" and includes your Git remote URL when available. Use --repository-id to require linked repository context, or --standalone to force a scan without repository context.

Limits

Limit	Value
Request JSON body	768 KiB
Submitted code input	256 KiB
Supplemental context	20 KiB
Files per request	20
Snippets per request	20
Result retention	7 days

Requests over these limits return 413.

Authentication

On-Demand Code Scans use the same API token headers as the rest of the ZeroPath API.

X-ZeroPath-API-Token-Id: YOUR_TOKEN_ID
X-ZeroPath-API-Token-Secret: YOUR_TOKEN_SECRET
Content-Type: application/json

For repository targets, the caller must be able to start scans on the target repository. For auto targets, ZeroPath uses repository context only when the submitted remote URL resolves to exactly one accessible repository. For standalone targets, the caller only needs authenticated organization context.

Getting Started

Scanning

SCA

Platform

Developer Tools

Integrations

Authentication

Overview

Target Modes

Submit a Scan

Poll Status

Fetch Results

Input Shapes

Diff

File

Files

Snippets

Supplemental Context

CLI Usage

Limits

Authentication

​Overview

​Target Modes

​Submit a Scan

​Poll Status

​Fetch Results

​Input Shapes

​Diff

​File

​Files

​Snippets

​Supplemental Context

​CLI Usage

​Limits

​Authentication

Overview

Target Modes

Submit a Scan

Poll Status

Fetch Results

Input Shapes

Diff

File

Files

Snippets

Supplemental Context

CLI Usage

Limits

Authentication