Skip to main content

Documentation Index

Fetch the complete documentation index at: https://zeropath.com/docs/llms.txt

Use this file to discover all available pages before exploring further.

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.
TargetUse when
autoRecommended 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.
repositoryYour integration already knows the ZeroPath repositoryId and should require linked repository context.
standaloneYou 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

LimitValue
Request JSON body768 KiB
Submitted code input256 KiB
Supplemental context20 KiB
Files per request20
Snippets per request20
Result retention7 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.