Run your first scan

Prerequisites

• A Pentify workspace and an API key with scans:write, targets:write and reports:read scopes — see Authentication.
• Control over a hostname you can scan (DNS or HTTP root).
• At least 5,000 tokens in the workspace balance for a standard scan — see Tokens & pricing.

Step 1 — verify the target

Pentify refuses to scan unverified hostnames. Two methods are supported; DNS TXT is the most reliable.

const target = await pentify.targets.create({
  hostname: "example.com",
  method: "dns_txt",
});

console.log(`Add DNS TXT at _pentify-verify.${target.hostname}`);
console.log(`Value: ${target.token}`);

// Once the record is live:
const verified = await pentify.targets.verify(target.id);
if (verified.status !== "verified") throw new Error("verification failed");

Step 2 — start the scan

Three scan_type values are available:

Step 3 — wait, then read the report

For small scans, polling every 30 seconds is fine. For standard and compliance, register a webhook first — see Webhooks.

const scan = await pentify.scans.create({
  target: "example.com",
  scanType: "standard",
});

while (scan.status === "queued" || scan.status === "running") {
  await new Promise((r) => setTimeout(r, 30_000));
  Object.assign(scan, await pentify.scans.retrieve(scan.id));
}

if (scan.status !== "completed") {
  throw new Error(`scan ${scan.status}`);
}

const { data: findings } = await pentify.reports.listFindings(scan.id);
const pdfUrl = await pentify.reports.pdfUrl(scan.id); // 30-min signed URL

What you get back

• findings — every issue Pentify identified, with CVSS v3.1 vector, severity, request / response evidence and reproduction steps.
• report.pdf — boardroom-ready PDF (302 redirect to a ~30-minute signed R2 URL).
• report (JSON) — the full structured report including attack-path graph and remediation playbooks.

What to do next

• Move from polling to webhooks for production workloads.
• Wire errors into your alerting stack — start with insufficient_tokens and target_not_verified.
• For autonomous-agent integrations, follow Integrate an autonomous agent.