Skip to main content

​
Scan a repo

Trigger a scan by providing a repository URL (or ref). You can wait for the scan to finish or poll for results.

​
SDK

import { Foundry } from '@withfoundry/sdk';

const foundry = new Foundry({ apiKey: process.env.FOUNDRY_API_KEY });

// Start scan (async; returns scanId)
const { data: scan } = await foundry.security.scanRepo({
  repoUrl: 'https://github.com/your-org/your-repo',
  branch: 'main',           // optional
  waitForCompletion: true,  // optional: wait and return findings
});

if (scan.status === 'completed') {
  console.log('Findings:', scan.findings);
  scan.findings.forEach((f) => {
    console.log(`${f.severity}: ${f.title} at ${f.file}:${f.line}`);
  });
} else {
  console.log('Scan ID:', scan.scanId, 'Status:', scan.status);
}

​
Poll for results

If you don’t use waitForCompletion, poll the scan result: 
const { data: scan } = await foundry.security.scanRepo({
  repoUrl: 'https://github.com/your-org/your-repo',
});

const scanId = scan.scanId;
let result = await foundry.security.getScanResult(scanId);

while (result.data.status === 'running' || result.data.status === 'pending') {
  await new Promise((r) => setTimeout(r, 5000));
  result = await foundry.security.getScanResult(scanId);
}

console.log('Findings:', result.data.findings);

​
REST API

Start scan: POST /v1/security/scan Headers: Authorization: Bearer key_...
Body: 
{
  "repoUrl": "https://github.com/your-org/your-repo",
  "branch": "main",
  "waitForCompletion": false
}
Response (started): 
{
  "success": true,
  "data": {
    "scanId": "scan_abc123",
    "status": "pending"
  },
  "meta": { "requestId": "req_xyz" }
}
Response (with waitForCompletion: true): 
{
  "success": true,
  "data": {
    "scanId": "scan_abc123",
    "status": "completed",
    "findings": [
      {
        "id": "fin_1",
        "severity": "high",
        "title": "Hardcoded secret pattern",
        "description": "Possible API key in source.",
        "file": "src/config.js",
        "line": 12,
        "suggestion": "Use environment variables."
      }
    ]
  },
  "meta": { "requestId": "req_xyz" }
}
Get result: GET /v1/security/scan/:scanId 
curl -H "Authorization: Bearer key_YOUR_KEY" \
  "https://api.withfoundry.ai/v1/security/scan/scan_abc123"

​
Finding shape

FieldTypeDescription
idstringFinding id.
severitystringcritical | high | medium | low | info.
titlestringShort title.
descriptionstringDetails.
filestringPath in repo.
linenumberLine number (optional range in extended shape).
suggestionstringOptional remediation.

​
CI example

Fail the build on high or critical: 
const { data } = await foundry.security.scanRepo({
  repoUrl: process.env.GITHUB_REPOSITORY
    ? `https://github.com/${process.env.GITHUB_REPOSITORY}`
    : 'https://github.com/your-org/your-repo',
  branch: process.env.GITHUB_REF_NAME || 'main',
  waitForCompletion: true,
});

const criticalOrHigh = data.findings?.filter(
  (f) => f.severity === 'critical' || f.severity === 'high'
) ?? [];
if (criticalOrHigh.length > 0) {
  console.error('Security findings:', criticalOrHigh);
  process.exit(1);
}
Next: Security API reference.