VSCan | API Documentation

rocket_launch Getting Started

The VSCan API allows you to scan VS Code extensions for security vulnerabilities programmatically. All requests require secure authentication via an API key snippet.

Authentication Protocol

Always include your active API key in the X-API-Key header for each secure request payload:

curl -H "X-API-Key: your-api-key" \
     https://vscan.dev/api/v1/status/your-analysis-id

key Generate Your API Key

Head over to the developer portal to instantly provision API credentials and quota.

Open Portal

link Base URL

https://vscan.dev/api/v1

api Core Endpoints

POST /scan

Submit a raw VS Code extension package configuration for multi-layered security analysis and intelligence scanning.

Request Payload Schema

Parameter	Type	Description
publisher required	string	The authoritative author/publisher identifier of the subject extension.
name required	string	The exact technical slug/name component of the subject extension.

Execution Example

curl -X POST https://vscan.dev/api/v1/scan \
     -H "Content-Type: application/json" \
     -H "X-API-Key: your-api-key" \
     -d '{"publisher": "ms-python", "name": "python"}'

const response = await fetch('https://vscan.dev/api/v1/scan', {
    method: 'POST',
    headers: {
        'Content-Type': 'application/json',
        'X-API-Key': 'your-api-key'
    },
    body: JSON.stringify({
        publisher: 'ms-python',
        name: 'python'
    })
});
const data = await response.json();
console.log(data.analysisId);

import requests

response = requests.post(
    'https://vscan.dev/api/v1/scan',
    headers={
        'Content-Type': 'application/json',
        'X-API-Key': 'your-api-key'
    },
    json={
        'publisher': 'ms-python',
        'name': 'python'
    }
)
data = response.json()
print(data['analysisId'])

Response Pattern (202 Accepted)

{
    "success": true,
    "analysisId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "status": "pending",
    "message": "Extension accepted for analysis.",
    "statusUrl": "/api/v1/status/a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "resultsUrl": "/api/v1/results/a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

GET /status/:analysisId

Poll the live status and execution progress of a triggered analysis workflow.

Path Parameters

Parameter	Type	Description
analysisId required	UUID	The 36-character tracking identifier injected via the `POST /scan` handler.

Execution Example

curl https://vscan.dev/api/v1/status/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
     -H "X-API-Key: your-api-key"

const response = await fetch('https://vscan.dev/api/v1/status/a1b2c3d4-e5f6-7890-abcd-ef1234567890', {
    method: 'GET',
    headers: {
        'X-API-Key': 'your-api-key'
    }
});
const data = await response.json();
console.log(data.status);

import requests

response = requests.get(
    'https://vscan.dev/api/v1/status/a1b2c3d4-e5f6-7890-abcd-ef1234567890',
    headers={
        'X-API-Key': 'your-api-key'
    }
)
data = response.json()
print(data['status'])

Response Pattern (200 OK)

{
    "success": true,
    "analysisId": "a1b...",
    "status": "processing",
    "progress": 45,
    "message": "Analyzing...",
    "resultsUrl": null
}

State Machine Enumerables

Status Enum	Directive Meaning
pending	Job queued. Awaiting available compute capacity.
processing	Job claimed. Executing dynamic intelligence tools.
completed	Execution finalized. Safe to query `/results`.
failed	Job threw a fatal exception. Package unavailable or incompatible.

GET /results/:analysisId

Extract the full normalized intelligence report and risk scores for a completed analysis.

Path Parameters

Parameter	Type	Description
analysisId required	UUID	The 36-character tracking identifier returned natively from the initial creation request.

Execution Example

curl https://vscan.dev/api/v1/results/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
     -H "X-API-Key: your-api-key"

const response = await fetch('https://vscan.dev/api/v1/results/a1b2c3d4-e5f6-7890-abcd-ef1234567890', {
    method: 'GET',
    headers: {
        'X-API-Key': 'your-api-key'
    }
});
const data = await response.json();
console.log(data.results.score);

import requests

response = requests.get(
    'https://vscan.dev/api/v1/results/a1b2c3d4-e5f6-7890-abcd-ef1234567890',
    headers={
        'X-API-Key': 'your-api-key'
    }
)
data = response.json()
print(data['results']['score'])

Response Pattern (200 OK)

{
    "success": true,
    "analysisId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "results": {
        "score": 85,
        "extensionInfo": {
            "publisher": "ms-python",
            "name": "python",
            "version": "2024.1.0"
        },
        "findings": [
            // Contains an exact array of isolated threats mapped by tool engine
            ...
        ],
        "summary": {
            // Aggregated statistical risk mapping factors
            ...
        }
    }
}

speed Rate Topologies

Scan Submission

POST /api/v1/scan — compute-heavy jobs

10/15m

Public API & Config

/api/v1/* status, results & config endpoints

30/15m

General API

All /api/* routes — catch-all ceiling

100/5m

error_outline Exception Mapping

HTTP	Semantics Mapping
400	Malformed parameter schema or absent target arguments
401	Key rejection / Empty `X-API-Key`
404	UUID identifier unmapped inside intelligence store
409	Conflict - Execution lock active on identical package
429	Rate limit exceeded — too many requests in the current window
500+	Gateway fallback. Native server crash.