Scanning API

The Scanning API allows you to programmatically trigger and monitor full scans of a branch. A scan started here is the same scan as the Scan button of a repository in the dashboard.

Manual codebase scans are available on Enterprise plans. Pull request scans run from the SCM integration and do not use this API.

Start a Scan

Endpoint

POST /v1/scan-workflows/start

Requires the permission codebase:scan (roles developer, security_engineer and admin).

Request Body

Field	Type	Required	Description
`codebaseId`	string	Yes	Repository (codebase) identifier. It must belong to the key’s project
`branch`	string	Yes	Git branch to scan
`scanSpecificFiles`	boolean	No	Default `false`. When `true`, only the files in `fileIds` are scanned
`fileIds`	string[]	Only with `scanSpecificFiles`	File IDs to scan. Required and non-empty when `scanSpecificFiles` is `true`; every ID must exist in the codebase

Example Request

curl -X POST https://api.vidoc.dev/v1/scan-workflows/start \
  -H "x-vidoc-token: $VIDOC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "codebaseId": "019f8a1b-0c2d-73e4-a5f6-7b8c9d0e1f2a",
    "branch": "main"
  }'

Response

201 Created:

{
  "id": "019f8a10-9e8d-7c6b-a5f4-3e2d1c0b9a87"
}

id is the scan ID. Use it with the status endpoint below. The scan starts as pending and moves to in_progress as soon as the workflow is running.

Scan Specific Files

To scan only certain files:

{
  "codebaseId": "019f8a1b-0c2d-73e4-a5f6-7b8c9d0e1f2a",
  "branch": "main",
  "scanSpecificFiles": true,
  "fileIds": [
    "019f8a1c-2d3e-7f40-a1b2-c3d4e5f60718",
    "019f8a1c-2d3e-7f40-a1b2-c3d4e5f60719"
  ]
}

See Finding File IDs for where the IDs come from.

Get Scan Status

Endpoint

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

Requires issue:view. The scan must belong to the key’s project; otherwise the API answers 404 Scan not found.

Example Request

curl https://api.vidoc.dev/v1/scan-workflows/019f8a10-9e8d-7c6b-a5f4-3e2d1c0b9a87/status \
  -H "x-vidoc-token: $VIDOC_API_KEY"

Response

{
  "id": "019f8a10-9e8d-7c6b-a5f4-3e2d1c0b9a87",
  "branch": "main",
  "type": "manual",
  "commit": "9f2c1e7b4d8a0c6e5f3b2a1d9c8e7f6a5b4c3d2e",
  "pullRequestId": null,
  "status": "completed",
  "projectId": "019f8a00-1b2c-7d3e-8f40-5a6b7c8d9e0f",
  "codebaseId": "019f8a1b-0c2d-73e4-a5f6-7b8c9d0e1f2a",
  "filesScannedCount": 312,
  "createdAt": "2026-09-18T10:30:00.000Z",
  "updatedAt": "2026-09-18T10:35:12.000Z"
}

Field	Description
`id`	The scan ID
`branch`	The scanned branch
`type`	`manual` for scans started by the API or the dashboard, `pull_request` for pull request scans
`commit`	The commit the scan read, or `null` when the branch state has no commit
`pullRequestId`	Set for pull request scans, `null` here
`status`	See Status Values
`filesScannedCount`	Number of files the scan processed so far
`createdAt`, `updatedAt`	ISO 8601 timestamps. `updatedAt` changes with every status change

The response is the scan record. It can carry more internal fields (for example githubCheckId and scmCheckId); ignore them. It has no issue count: once the status is completed, read the results with GET /v1/issues?codebaseId=....

Status Values

Status	Description
`pending`	Scan record created, workflow not started yet
`in_progress`	Scan running
`completed`	Scan finished successfully
`failed`	Scan encountered an error, or the workflow could not start
`superseded`	A newer scan of the same pull request replaced this one (pull request scans only)

Polling for Completion

Poll the status endpoint until the scan reaches a final state:

async function waitForScan(scanId, apiKey) {
  const maxAttempts = 120;
  const delayMs = 5000;

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

    const scan = await response.json();

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

    if (scan.status === 'failed' || scan.status === 'superseded') {
      throw new Error(`Scan ended with status ${scan.status}`);
    }

    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

Go to Repositories
Click a repository
The codebase ID is the last segment of the URL: /projects/<projectId>/repositories/<codebaseId>

Via API

GET /v1/codebase lists the repositories of the key’s project (permission issue:view). Each item carries id, name, url and defaultBranchName, among other fields. GET /v1/codebase/:codebaseId returns one repository.

curl https://api.vidoc.dev/v1/codebase \
  -H "x-vidoc-token: $VIDOC_API_KEY"

Finding File IDs

For scanSpecificFiles, list the files of a branch:

GET /v1/codebase/:codebaseId/files?branchName=main

branchName is required. The response is { "files": [...] }, and each file has fileId, filePath, version, isIndexed and isScanned. Use fileId in fileIds.

Error Handling

Common Errors

Error	HTTP	Cause	Solution
`Validation failed`	`400`	`codebaseId` or `branch` missing or empty, or `scanSpecificFiles` is `true` without `fileIds`	Read the `errors` array
`Codebase not found`	`404`	The `codebaseId` does not exist, was deleted, or belongs to another project	Verify the ID with `GET /v1/codebase`
`The following file IDs do not exist in this codebase: ...`	`404`	One or more `fileIds` are unknown	Verify the IDs with the files route
`Scan not found`	`404`	The `scanId` does not exist or belongs to another project	Verify the scan ID
`Internal server error`	`500`	The plan does not allow a manual scan (Enterprise only), the organization has no active subscription, or the workflow could not start	Check the plan; if it allows manual scans, retry and contact support

A plan restriction is answered with 500 Internal server error today, and the body carries no detail. If a scan start fails with 500 on a non-Enterprise plan, that is the cause.

Error Response Format

{
  "statusCode": 404,
  "message": "Codebase not found",
  "error": "Not Found",
  "timestamp": "2026-09-18T10:30:00.000Z",
  "path": "/v1/scan-workflows/start"
}

See API Authentication for the full error contract.

Rate Limits

The API does not rate-limit requests today. Poll the status endpoint every few seconds, not in a tight loop.

Complete Example

const VIDOC_API_KEY = process.env.VIDOC_API_KEY;
const API_BASE = 'https://api.vidoc.dev/v1';
const headers = {
  'x-vidoc-token': VIDOC_API_KEY,
  'Content-Type': 'application/json',
};

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

  if (!startResponse.ok) {
    throw new Error(`Scan start failed: ${startResponse.status}`);
  }

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

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

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

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

  if (status !== 'completed') {
    throw new Error(`Scan ended with status ${status}`);
  }

  // Read the results
  const issuesResponse = await fetch(
    `${API_BASE}/issues?codebaseId=${codebaseId}&branch=${encodeURIComponent(branch)}`,
    { headers },
  );
  const { total } = await issuesResponse.json();
  console.log(`Found ${total} open issues`);
}

runScan('019f8a1b-0c2d-73e4-a5f6-7b8c9d0e1f2a', 'main');

API Authentication

Authentication setup

Issues API

Access scan results

CLI Scanning

CLI alternative

CI/CD Integration

Automate scans

Get Started

Dashboard

GitHub Integration

CLI

Security Categories

Settings

API Reference

Other Integrations

Scanning API

Start a Scan

Endpoint

Request Body

Example Request

Response

Scan Specific Files

Get Scan Status

Endpoint

Example Request

Response

Status Values

Polling for Completion

Finding Your Codebase ID

Via Dashboard

Via API

Finding File IDs

Error Handling

Common Errors

Error Response Format

Rate Limits

Complete Example

API Authentication

Issues API

CLI Scanning

CI/CD Integration

​Start a Scan

​Endpoint

​Request Body

​Example Request

​Response

​Scan Specific Files

​Get Scan Status

​Endpoint

​Example Request

​Response

​Status Values

​Polling for Completion

​Finding Your Codebase ID

​Via Dashboard

​Via API

​Finding File IDs

​Error Handling

​Common Errors

​Error Response Format

​Rate Limits

​Complete Example

​Related Pages

API Authentication

Issues API

CLI Scanning

CI/CD Integration

Start a Scan

Endpoint

Request Body

Example Request

Response

Scan Specific Files

Get Scan Status

Endpoint

Example Request

Response

Status Values

Polling for Completion

Finding Your Codebase ID

Via Dashboard

Via API

Finding File IDs

Error Handling

Common Errors

Error Response Format

Rate Limits

Complete Example

Related Pages