Initiate scans, poll status, and fetch findings

The Zero Cool Scan API lets a workspace API key initiate scans, read scan results, and continue failed scans from external tools and coding agents.

Overview

Workspace API Key

Create a workspace-scoped key in Workspace Administration. The key can only see scans for its workspace.

Initiate Scans

Start a scan by sending the repository URL and target commit. Include a base commit when you want a diff review.

Read Scan Results

List scans, fetch one scan by ID, and read findings once Zero Cool completes the scan.

Continue Failed Scans

Queue a continuation when a failed scan has saved runtime state.

Create an API key

Create keys from the Zero Cool web app. The secret appears once, so store it before leaving the page.

• Open the workspace selector in the upper-right corner, then click the gear icon next to the workspace.
• Choose Workspace Administration, then open Scan API Keys.
• Enter a key name, choose the permissions, and click Create key. Copy the secret immediately.
• Set read access to This workspace. Leave Allow scan starts enabled when the key should start scans.

Treat the API key like a password. Do not paste it into source files, issue comments, logs, or public chat.

Quickstart

A diff review compares a head commit against a base commit. Diff-review-only workspaces reject requests that omit base_commit.

export ZC_API_KEY="zc_..."
export ZC_API_BASE="https://api.zerocool.ai/api/v1"

curl -sS -X POST "$ZC_API_BASE/scans" \
  -H "Authorization: Bearer $ZC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "repository_url": "https://github.com/Uniswap/v4-periphery",
    "git_branch": "margin-trading",
    "git_commit": "1db2c5dad1da882ad50533d8832adec3bfc7a929",
    "base_commit": "363226d9e1e2180b67bf6857023dbaad751010c5",
    "scan_name": "Zero Cool diff review"
  }'

{
  "scan_id": "b8c96174-6b66-426a-abf3-f93a086e7dff",
  "status": "queued"
}

curl -sS -H "Authorization: Bearer $ZC_API_KEY" \
  "$ZC_API_BASE/scans/<scan_id>"

Agent workflow

Give the agent the API key through its environment, then give it the repository URL, head commit, and base commit.

Use the Zero Cool Scan API. Start a Zero Cool diff review for this repository and commit range, poll until it completes, then include Zero Cool findings in the combined security review. Deduplicate Zero Cool findings against other tools by affected code area and exploit path.

• Require ZC_API_KEY and ZC_API_BASE.
• Send repository_url, git_commit, and base_commit for a diff review.
• Do not send scanner config, templates, lead generators, tags, workspace IDs, or credentials.
• Poll the returned scan_id until status is completed or failed.
• If a scan fails with error.retryable = true, offer continuation and handle a 400 rejection.
• Report the Zero Cool scan_id with the final summary.

Endpoints

Starts a scan for the API key workspace and returns a scan ID immediately. Include base_commit to start a diff review.

Lists scans visible to the API key workspace, newest first.

Returns one scan plus its error object and findings. Statuses are queued, running, completed, or failed. Completed scans include findings when Zero Cool produced them. Failed scans include error.message and error.retryable.

Queues a continuation of a failed same-workspace scan. The server uses the original repository, commit, config template, worker config, and saved scan state.

curl -sS -X POST "$ZC_API_BASE/scans/<scan_id>/continue" \
  -H "Authorization: Bearer $ZC_API_KEY"

Errors

Every error uses this envelope:

{ "error": "human-readable message" }

Operational notes

• API keys are workspace-scoped. A key sees only scans for its workspace.
• Maximum 10 requests per minute per key.
• Accepted scans appear in the list immediately as queued.