> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vidocsecurity.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Scanning API

> Start and monitor security scans via the REST API

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

## Start a Scan

### Endpoint

```
POST /v1/scan-workflows/start
```

### Request Body

| Field               | Type      | Required | Description                               |
| ------------------- | --------- | -------- | ----------------------------------------- |
| `codebaseId`        | string    | Yes      | Repository/codebase identifier            |
| `branch`            | string    | Yes      | Git branch to scan                        |
| `scanSpecificFiles` | boolean   | No       | Only scan specific files                  |
| `fileIds`           | string\[] | No       | File IDs to scan (if `scanSpecificFiles`) |

### Example Request

```bash theme={null}
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

```json theme={null}
{
  "id": "scan_xyz789"
}
```

### Scan Specific Files

To scan only certain files:

```json theme={null}
{
  "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

```bash theme={null}
curl https://api.vidocsecurity.com/v1/scan-workflows/scan_xyz789/status \
  -H "Authorization: Bearer $VIDOC_API_KEY"
```

### Response

```json theme={null}
{
  "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

| Status      | Description                |
| ----------- | -------------------------- |
| `pending`   | Scan queued                |
| `running`   | Scan in progress           |
| `completed` | Scan finished successfully |
| `failed`    | Scan encountered an error  |

## Polling for Completion

Poll the status endpoint until the scan completes:

```javascript theme={null}
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

| Error                | Cause                | Solution             |
| -------------------- | -------------------- | -------------------- |
| `Codebase not found` | Invalid codebaseId   | Verify the ID exists |
| `Branch not found`   | Branch doesn't exist | Check branch name    |
| `Invalid file IDs`   | File IDs don't exist | Verify file IDs      |

### Error Response Format

```json theme={null}
{
  "statusCode": 404,
  "message": "Codebase not found",
  "error": "Not Found"
}
```

## Rate Limits

| Operation  | Limit          |
| ---------- | -------------- |
| Start scan | 10 per minute  |
| Get status | 100 per minute |

If rate limited, wait and retry:

```javascript theme={null}
if (response.status === 429) {
  const retryAfter = response.headers.get('Retry-After') || 60;
  await new Promise(resolve => setTimeout(resolve, retryAfter * 1000));
  // Retry request
}
```

## Complete Example

```javascript theme={null}
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');
```

## Related Pages

<CardGroup cols={2}>
  <Card title="API Authentication" icon="key" href="/api/authentication">
    Authentication setup
  </Card>

  <Card title="Issues API" icon="bug" href="/api/issues">
    Access scan results
  </Card>

  <Card title="CLI Scanning" icon="terminal" href="/cli/scanning">
    CLI alternative
  </Card>

  <Card title="CI/CD Integration" icon="gear" href="/cli/ci-cd">
    Automate scans
  </Card>
</CardGroup>