API Documentation

The VSCan API lets you scan VS Code extensions for security vulnerabilities programmatically. Extensions can come from the VS Code Marketplace or the Open VSX Registry.

key Generate your API key

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

Open Portal

schema

How It Works

Scanning is asynchronous. You submit an extension, receive an analysisId, poll the status endpoint until it reports completed, then fetch the full report.

01 POST

Submit a scan

Send a publisher + name to /scan. Get back an analysisId.

02 GET

Poll the status

Call /status/:id until status is completed.

03 GET

Fetch results

Call /results/:id for the risk score and findings.

All endpoints at a glance

POST /scan Submit an extension for analysis GET /status/:analysisId Check whether a scan has finished GET /results/:analysisId Retrieve the score and findings GET /monitored-extensions List your monitored extensions POST /monitored-extensions Add an extension to a monitored slot DELETE /monitored-extensions Remove an extension from a slot DELETE /monitored-extensions/all Clear the whole list (24h after renewal/upgrade)

lock

Authentication

Authenticate your requests by including your active API key in the X-API-Key header of every request.

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

const response = await fetch('https://vscan.dev/api/v1/status/your-analysis-id', {
    headers: { 'X-API-Key': 'your-api-key' }
});

import requests

response = requests.get(
    'https://vscan.dev/api/v1/status/your-analysis-id',
    headers={ 'X-API-Key': 'your-api-key' }
)

link

Base URL

All endpoints are relative to the following base URL.

Base URL

https://vscan.dev/api/v1

api

Scanning

The three-step async flow: submit an extension, poll its status, then fetch the results.

POST

Submit a Scan

/scan

Queue an extension for security analysis. Returns immediately with an analysisId you'll use to track progress and fetch results. Works with both the VS Code Marketplace and Open VSX Registry.

Request Body

publisherRequired

The author/publisher identifier (namespace) of the extension.

nameRequired

The technical slug/name of the extension.

registryOptional

"marketplace" (default) or "openvsx".

Example Request

# VS Code Marketplace (default)
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"}'

# Open VSX Registry
curl -X POST https://vscan.dev/api/v1/scan \
     -H "Content-Type: application/json" \
     -H "X-API-Key: your-api-key" \
     -d '{"publisher": "esbenp", "name": "prettier-vscode", "registry": "openvsx"}'

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',
        registry: 'marketplace' // or 'openvsx'
    })
});
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',
        'registry': 'marketplace'  # or 'openvsx'
    }
)
data = response.json()
print(data['analysisId'])

Response · 202 Accepted

JSON

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

GET

Check Scan Status

/status/:analysisId

Check whether a scan has finished. Poll this endpoint until status is completed, then call /results.

Path Parameters

analysisIdRequired

The analysisId returned by POST /scan.

Example Request

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-...', {
    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-...',
    headers={ 'X-API-Key': 'your-api-key' }
)
data = response.json()
print(data['status'])

Response · 200 OK

JSON

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

Status Values

pendingQueued, awaiting compute.

processingExecuting analysis tools.

completedDone — query /results.

failedPackage unavailable/incompatible.

GET

Get Scan Results

/results/:analysisId

Retrieve the full report — risk score, extension info, and findings — for a completed scan.

Path Parameters

analysisIdRequired

The analysisId returned by POST /scan.

Example Request

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-...', {
    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-...',
    headers={ 'X-API-Key': 'your-api-key' }
)
data = response.json()
print(data['results']['score'])

Response · 200 OK

JSON

{
    "success": true,
    "analysisId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "results": {
        "score": 85,
        "extensionInfo": {
            "publisher": "ms-python",
            "name": "python",
            "version": "2024.1.0"
        },
        "findings": [
            // One entry per detected issue, grouped by scanner
            ...
        ],
        "summary": {
            // Counts of findings by severity
            ...
        }
    }
}

inventory_2

Monitored Extensions

A monitored extension occupies a "slot" in your account and is tracked continuously against VSCan's marketplace threat intelligence. These endpoints let you list, add, and remove slots programmatically, up to your plan's slot limit.

info

These endpoints authenticate the same way — include your API key in the X-API-Key header. You can also manage slots visually in the API Portal.

GET

List Monitored

/api/v1/monitored-extensions

List all extensions currently occupying a monitored slot in your account.

Example Request

curl https://vscan.dev/api/v1/monitored-extensions \
     -H "X-API-Key: your-api-key"

const response = await fetch('https://vscan.dev/api/v1/monitored-extensions', {
    headers: { 'X-API-Key': 'your-api-key' }
});
const data = await response.json();
console.log(data.extensions);

import requests

response = requests.get(
    'https://vscan.dev/api/v1/monitored-extensions',
    headers={ 'X-API-Key': 'your-api-key' }
)
print(response.json()['extensions'])

Response · 200 OK

JSON

{
    "extensions": [
        {
            "extensionId": "ms-python.python",
            "publisher": "ms-python",
            "name": "python",
            "registry": "marketplace",
            "addedAt": "2026-05-01T12:00:00.000Z",
            "lastScannedAt": "2026-06-01T08:30:00.000Z"
        }
    ]
}

POST

Add Monitored

/api/v1/monitored-extensions

Add an extension to a monitored slot. Fails with 403 if you've reached your plan's slot limit, or 409 if the extension is already monitored.

Request Body

publisherRequired

The author/publisher identifier (namespace) of the extension.

nameRequired

The technical slug/name of the extension.

registryOptional

"marketplace" (default) or "openvsx".

Example Request

curl -X POST https://vscan.dev/api/v1/monitored-extensions \
     -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/monitored-extensions', {
    method: 'POST',
    headers: {
        'Content-Type': 'application/json',
        'X-API-Key': 'your-api-key'
    },
    body: JSON.stringify({ publisher: 'ms-python', name: 'python' })
});

import requests

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

Response · 201 Created

JSON

{
    "message": "Extension added successfully.",
    "extensionId": "ms-python.python"
}

DELETE

Remove Monitored

/api/v1/monitored-extensions

Remove an extension from a monitored slot, freeing it for another. Counts against your plan's per-cycle slot swap limit (403 if exceeded).

Request Body

publisherRequired

The author/publisher identifier (namespace) of the extension.

nameRequired

The technical slug/name of the extension.

registryOptional

Must match the registry the slot was created in — "marketplace" (default) or "openvsx".

Example Request

curl -X DELETE https://vscan.dev/api/v1/monitored-extensions \
     -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/monitored-extensions', {
    method: 'DELETE',
    headers: {
        'Content-Type': 'application/json',
        'X-API-Key': 'your-api-key'
    },
    body: JSON.stringify({ publisher: 'ms-python', name: 'python' })
});

import requests

response = requests.delete(
    'https://vscan.dev/api/v1/monitored-extensions',
    headers={
        'Content-Type': 'application/json',
        'X-API-Key': 'your-api-key'
    },
    json={ 'publisher': 'ms-python', 'name': 'python' }
)

Response · 200 OK

JSON

{
    "message": "Extension removed successfully.",
    "extensionId": "ms-python.python"
}

DELETE

Clear All Monitored

/api/v1/monitored-extensions/all

Remove every extension from your monitored list in one call so you can start a fresh list — without spending any slot swaps.

schedule

This reset is only available for 24 hours after your subscription renews or is upgraded, and only once per cycle. Outside that window it returns 403 Not Available. Downgrades clear the list automatically, so this endpoint is not needed for them.

Example Request

curl -X DELETE https://vscan.dev/api/v1/monitored-extensions/all \
     -H "X-API-Key: your-api-key"

const response = await fetch('https://vscan.dev/api/v1/monitored-extensions/all', {
    method: 'DELETE',
    headers: { 'X-API-Key': 'your-api-key' }
});

import requests

response = requests.delete(
    'https://vscan.dev/api/v1/monitored-extensions/all',
    headers={ 'X-API-Key': 'your-api-key' }
)

Response · 200 OK

JSON

{
    "success": true,
    "message": "Monitored extension list cleared.",
    "cleared": 42
}

menu_book

Reference

speed Rate Limits

Scan Submission

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

10/15m

Public API & Config

/api/v1/* status, results & config

30/15m

General API

All /api/* routes — catch-all ceiling

100/5m

error_outline Error Codes

400Bad request — a required field is missing or invalid

401Missing or invalid X-API-Key header

403Plan limit reached — out of monitored slots or slot swaps

404No scan or extension found for that identifier

409Conflict — the extension is already monitored

429Rate limit exceeded — too many requests in the window

500Something went wrong on our end — retry shortly