> ## 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 Beta > Submit diffs, files, and snippets for asynchronous security review 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. ```bash theme={null} 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`: ```json theme={null} { "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`. ```bash theme={null} 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. ```bash theme={null} 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: ```json theme={null} { "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 ```json theme={null} { "kind": "diff", "diff": "diff --git a/api.ts b/api.ts\n..." } ``` ### File ```json theme={null} { "kind": "file", "path": "src/api.ts", "language": "typescript", "content": "export async function handler(req) { ... }" } ``` ### Files ```json theme={null} { "kind": "files", "files": [ { "path": "src/api.ts", "language": "typescript", "content": "..." } ] } ``` ### Snippets ```json theme={null} { "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. ```json theme={null} { "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. ```bash theme={null} # 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. ```bash theme={null} 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.