Skip to main content
The Scanning API allows you to programmatically trigger and monitor security scans.

​
Start a Scan

​
Endpoint

POST /v1/scan-workflows/start

​
Request Body

FieldTypeRequiredDescription
codebaseIdstringYesRepository/codebase identifier
branchstringYesGit branch to scan
scanSpecificFilesbooleanNoOnly scan specific files
fileIdsstring[]NoFile IDs to scan (if scanSpecificFiles)

​
Example Request

curl -X POST https://api.vidocsecurity.com/v1/scan-workflows/start \
  -H "Authorization: Bearer $VIDOC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "codebaseId": "codebase_abc123",
    "branch": "main"
  }'

​
Response

{
  "id": "scan_xyz789"
}

​
Scan Specific Files

To scan only certain files: 
{
  "codebaseId": "codebase_abc123",
  "branch": "main",
  "scanSpecificFiles": true,
  "fileIds": ["file_1", "file_2", "file_3"]
}

​
Get Scan Status

​
Endpoint

GET /v1/scan-workflows/:scanId/status

​
Example Request

curl https://api.vidocsecurity.com/v1/scan-workflows/scan_xyz789/status \
  -H "Authorization: Bearer $VIDOC_API_KEY"

​
Response

{
  "id": "scan_xyz789",
  "status": "completed",
  "projectId": "proj_abc",
  "codebaseId": "codebase_abc123",
  "branch": "main",
  "createdAt": "2024-01-15T10:30:00Z",
  "completedAt": "2024-01-15T10:35:00Z",
  "issuesFound": 3
}

​
Status Values

StatusDescription
pendingScan queued
runningScan in progress
completedScan finished successfully
failedScan encountered an error

​
Polling for Completion

Poll the status endpoint until the scan completes: 
async function waitForScan(scanId, apiKey) {
  const maxAttempts = 60;
  const delayMs = 5000;

  for (let i = 0; i < maxAttempts; i++) {
    const response = await fetch(
      `https://api.vidocsecurity.com/v1/scan-workflows/${scanId}/status`,
      {
        headers: { 'Authorization': `Bearer ${apiKey}` }
      }
    );

    const scan = await response.json();

    if (scan.status === 'completed') {
      return scan;
    }

    if (scan.status === 'failed') {
      throw new Error('Scan failed');
    }

    await new Promise(resolve => setTimeout(resolve, delayMs));
  }

  throw new Error('Scan timed out');
}

​
Finding Your Codebase ID

The codebaseId is required to start a scan. Find it:

​
Via Dashboard

  1. Go to Repositories
  2. Click a repository
  3. The codebase ID is in the URL: /repositories/codebase_abc123

​
Via API

List repositories to get codebase IDs (contact support for this endpoint documentation).

​
Error Handling

​
Common Errors

ErrorCauseSolution
Codebase not foundInvalid codebaseIdVerify the ID exists
Branch not foundBranch doesn’t existCheck branch name
Invalid file IDsFile IDs don’t existVerify file IDs

​
Error Response Format

{
  "statusCode": 404,
  "message": "Codebase not found",
  "error": "Not Found"
}

​
Rate Limits

OperationLimit
Start scan10 per minute
Get status100 per minute
If rate limited, wait and retry: 
if (response.status === 429) {
  const retryAfter = response.headers.get('Retry-After') || 60;
  await new Promise(resolve => setTimeout(resolve, retryAfter * 1000));
  // Retry request
}

​
Complete Example

const VIDOC_API_KEY = process.env.VIDOC_API_KEY;
const API_BASE = 'https://api.vidocsecurity.com/v1';

async function runScan(codebaseId, branch) {
  // Start scan
  const startResponse = await fetch(`${API_BASE}/scan-workflows/start`, {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${VIDOC_API_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ codebaseId, branch }),
  });

  const { id: scanId } = await startResponse.json();
  console.log(`Scan started: ${scanId}`);

  // Wait for completion
  let status = 'pending';
  while (status === 'pending' || status === 'running') {
    await new Promise(r => setTimeout(r, 5000));

    const statusResponse = await fetch(
      `${API_BASE}/scan-workflows/${scanId}/status`,
      {
        headers: { 'Authorization': `Bearer ${VIDOC_API_KEY}` },
      }
    );

    const scan = await statusResponse.json();
    status = scan.status;
    console.log(`Status: ${status}`);

    if (status === 'completed') {
      console.log(`Found ${scan.issuesFound} issues`);
      return scan;
    }

    if (status === 'failed') {
      throw new Error('Scan failed');
    }
  }
}

runScan('codebase_abc123', 'main');

API Authentication

Authentication setup

Issues API

Access scan results

CLI Scanning

CLI alternative

CI/CD Integration

Automate scans