Scanning API

Before you run these examples, select your deployment API address. Set VIDOC_API_URL without a trailing slash or /v1, and keep the key in VIDOC_API_KEY. The Scanning API starts and monitors full scans of a repository. There are two routes to start a scan:

Route	Use it for
`POST /v1/scans`	The same scans as the options menu of a repository in the web app: Run scan, Rescan from scratch and Revalidate findings. Vidoc scans the source branch of the repository. Use this route for scripts and automation.
`POST /v1/scan-workflows/start`	A scan of any branch, or of some files, of a repository that the CLI uploaded. The `vidoc` CLI uses this route.

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

Start a Full Scan

Endpoint

POST /v1/scans

Starts a full scan of the source branch of one repository. If the repository is connected through GitHub, GitLab, or Bitbucket, Vidoc first reads the latest commit of the branch. The route needs a user API key. System, GitHub, and legacy tokens get 403 user_token_required, because Vidoc records who started the scan in the audit log.

Request Body

Field	Type	Required	Description
`codebaseId`	string	Yes	Repository (codebase) identifier. It must belong to the key’s project
`mode`	string	No	`incremental` (default), `fresh`, or `revalidate`. See Scan modes

The route has no branch field: Vidoc always scans the source branch. To change it, refer to Repositories. A field that the route does not know gives 400 unknown_parameter.

Scan Modes

Mode	Web app action	What Vidoc does	Permission
`incremental`	Run scan	Scans the new and changed files. A file that did not change keeps its findings.	`codebase:scan` (roles `developer`, `security_engineer`, `admin`)
`fresh`	Rescan from scratch	Retires the open, closed, and false-positive findings of the branch, then detects and validates every file again with the current memories. Fixed findings and accepted risks stay.	`org:manage_scans` (role `admin`)
`revalidate`	Revalidate findings	Validates every open finding of the last full scan again with the current memories. A finding that is now a false positive closes. Vidoc does not detect new findings.	`org:manage_scans` (role `admin`)

Use fresh or revalidate after your team adds memories, to apply them to findings that Vidoc validated before.

fresh retires findings: they leave the dashboard, and the scan finds them again as new findings. Use it only when you want a new baseline for the branch. Ask your team before you start it from a script.

Example Request

curl -X POST "${VIDOC_API_URL:?Set VIDOC_API_URL to your deployment URL}/v1/scans" \
  -H "x-vidoc-token: $VIDOC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "codebaseId": "019f8a1b-0c2d-73e4-a5f6-7b8c9d0e1f2a",
    "mode": "incremental"
  }'

Response

202 Accepted:

{
  "scanId": "019f8a10-9e8d-7c6b-a5f4-3e2d1c0b9a87",
  "codebaseId": "019f8a1b-0c2d-73e4-a5f6-7b8c9d0e1f2a",
  "branch": "main",
  "mode": "incremental"
}

The scan runs after the response. Use scanId with the status endpoint, or find the scan in GET /v1/scans. branch is the source branch that Vidoc scans.

When the Scan Does Not Start

HTTP	`code`	Cause
`403`	`user_token_required`	The key has no user (system, GitHub, or legacy token)
`403`	`permission_missing`	The role does not have the permission of the mode. `fresh` and `revalidate` need the `admin` role
`403`	`plan_not_allowed`	The plan does not include manual codebase scans (Enterprise only)
`404`	`codebase_not_found`	The `codebaseId` does not exist, was deleted, or belongs to another project
`409`	`scan_running`	A scan of the repository runs. Wait until it completes
`409`	`learning_in_progress`	`fresh` only: Vidoc is creating a memory from a finding of this repository. Retry in a few minutes
`409`	`no_completed_scan`	`revalidate` only: the source branch has no completed full scan. Run an `incremental` scan first
`409`	`branch_changed`	`revalidate` only: the source branch changed after its last full scan. Run an `incremental` scan first

Branch your code on code, not on message. Refer to API Authentication for the error body.

Start a Scan of a Branch

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 "${VIDOC_API_URL:?Set VIDOC_API_URL to your deployment URL}/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 "${VIDOC_API_URL:?Set VIDOC_API_URL to your deployment URL}/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, when available. Manual and CLI scans can return `null`; do not infer a commit from the branch name.
`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)

List Scans

GET /v1/scans

Returns the scans of the project, newest first.

Query Parameters

string

The ID of a repository. Get it from GET /v1/codebase.

string

A branch name. You can use it without codebaseId. Then the API returns the scans of that branch in all repositories.

string

push, pull_request, or manual.

string

pending, in_progress, completed, failed, or superseded.

integer

default:"50"

The number of scans on one page, from 1 to 100.

integer

default:"0"

The number of scans to skip.

A parameter that the endpoint does not know gives the error unknown_parameter. An unknown codebaseId gives codebase_not_found.

Example Request

curl -s -G "${VIDOC_API_URL:?Set VIDOC_API_URL to your deployment URL}/v1/scans" \
  -H "x-vidoc-token: $VIDOC_API_KEY" \
  --data-urlencode "codebaseId=$CODEBASE_ID" \
  --data-urlencode "branch=main" \
  --data-urlencode "limit=5"

Response

{
  "scans": [
    {
      "scanId": "0199a1a9-...",
      "codebaseId": "0198f3c4-...",
      "branch": "main",
      "type": "manual",
      "status": "completed",
      "commitSha": null,
      "pullRequestId": null,
      "filesScannedCount": 214,
      "createdAt": "2026-09-24T09:02:11.000Z",
      "updatedAt": "2026-09-24T09:12:40.000Z"
    }
  ],
  "total": 1,
  "limit": 5,
  "offset": 0
}

Field	Type	Meaning
`scanId`	string	The ID of the scan. Use it with the status endpoint, and with `codebaseId` and `branch` in the issue filters.
`codebaseId`	string \| null	The ID of the repository.
`branch`	string	The scanned branch.
`type`	string \| null	`push`, `pull_request`, or `manual`.
`status`	string	Refer to Status Values.
`commitSha`	string \| null	The scanned commit, when Vidoc knows it.
`pullRequestId`	string \| null	The Vidoc ID of the PR, for PR scans.
`filesScannedCount`	integer	The number of scanned files.
`createdAt`	string	The time when Vidoc created the scan.
`updatedAt`	string	The time of the last change of the scan.

total is the number of scans that agree with the filters, on all pages.

Polling for Completion

Poll the status endpoint until the scan reaches a final state. It works for scans from both start routes:

async function waitForScan(scanId, apiKey) {
  const apiUrl = process.env.VIDOC_API_URL;
  if (!apiUrl) throw new Error('Set VIDOC_API_URL to your deployment URL');
  const maxAttempts = 120;
  const delayMs = 5000;

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

    if (!response.ok) throw new Error(`Status request failed: ${response.status}`);
    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

Both start routes need a codebaseId. 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 "${VIDOC_API_URL:?Set VIDOC_API_URL to your deployment URL}/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

For the errors of POST /v1/scans, refer to When the Scan Does Not Start. This table is for POST /v1/scan-workflows/start and the status route.

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

POST /v1/scan-workflows/start answers a plan restriction with 500 Internal server error, and the body carries no detail. If a scan start fails with 500 on a non-Enterprise plan, that is the cause. POST /v1/scans answers 403 plan_not_allowed instead.

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 apiUrl = process.env.VIDOC_API_URL;
if (!apiUrl) throw new Error('Set VIDOC_API_URL to your deployment URL');
const API_BASE = `${apiUrl}/v1`;
const headers = {
  'x-vidoc-token': VIDOC_API_KEY,
  'Content-Type': 'application/json',
};

async function runScan(codebaseId, mode = 'incremental') {
  // Start a full scan of the source branch
  const startResponse = await fetch(`${API_BASE}/scans`, {
    method: 'POST',
    headers,
    body: JSON.stringify({ codebaseId, mode }),
  });

  if (!startResponse.ok) {
    const error = await startResponse.json();
    throw new Error(`Scan start failed: ${startResponse.status} ${error.code}`);
  }

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

  // 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 },
    );

    if (!statusResponse.ok) {
      throw new Error(`Status request failed: ${statusResponse.status}`);
    }
    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 },
  );
  if (!issuesResponse.ok) {
    throw new Error(`Issues request failed: ${issuesResponse.status}`);
  }
  const { total } = await issuesResponse.json();
  console.log(`Found ${total} open issues`);
}

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

API Authentication

Authentication setup

Issues API

Access scan results

CLI Scanning

CLI alternative

CI/CD Integration

Automate scans

​Start a Full Scan

​Endpoint

​Request Body

​Scan Modes

​Example Request

​Response

​When the Scan Does Not Start

​Start a Scan of a Branch

​Endpoint

​Request Body

​Example Request

​Response

​Scan Specific Files

​Get Scan Status

​Endpoint

​Example Request

​Response

​Status Values

​List Scans

​Query Parameters

​Example Request

​Response

​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 Full Scan

Endpoint

Request Body

Scan Modes

Example Request

Response

When the Scan Does Not Start

Start a Scan of a Branch

Endpoint

Request Body

Example Request

Response

Scan Specific Files

Get Scan Status

Endpoint

Example Request

Response

Status Values

List Scans

Query Parameters

Example Request

Response

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