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.
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
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
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
| 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:
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
- Go to Repositories
- Click a repository
- 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 |
{
"statusCode": 404,
"message": "Codebase not found",
"error": "Not Found"
}
Rate Limits
| Operation | Limit |
|---|
| Start scan | 10 per minute |
| Get status | 100 per minute |
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');
Related Pages
API Authentication
Authentication setup
Issues API
Access scan results
CLI Scanning
CLI alternative
CI/CD Integration
Automate scans
