REST API Reference - VEXLIT Docs

REST API v1

API Reference

Automate security scanning in CI/CD with a single API call.

Try it now — copy, paste, scan:

curl -X POST https://vexlit.ai/api/v1/scan \
  -H "Authorization: Bearer vex_sk_your_key" \
  -H "Content-Type: application/json" \
  -d '{"project_id": "your_project_id"}'

{
  "scan_id": "abc123-...",
  "status": "queued"
}

Read APIs — All plans

List projects, scans, vulnerabilities, download SARIF

scan:create — Team plan + team projects

Trigger scans via API for CI/CD automation

Setup

Base URL

https://vexlit.ai/api/v1

Authentication

Include your API key in the Authorization header. Create keys in Dashboard > API Keys.

curl -H "Authorization: Bearer vex_sk_xxxxx.yyyyy" https://vexlit.ai/api/v1/projects

Plan Access

Plan	Access	Keys	Rate Limit
Free	Read-only	1	30 req/h
Pro	Read-only	2	60 req/h
Team	Full (read + write)	3	100 req/h
Enterprise	Full (read + write)	Unlimited	1,000 req/h

scan:create (write) requires Team plan or higher and only works on team projects.

Scopes

Scope	Description	Required Plan
scan:read	List scans, view scan details and SARIF	All plans
project:read	List projects	All plans
vuln:read	View vulnerabilities for a project	All plans
scan:create	Create and queue scans (team projects only)	Team+

Error Responses

All errors follow a consistent format with error code and human-readable message.

{
  "error": "plan_required",
  "message": "scan:create requires Team plan or higher. Effective plan: free"
}

HTTP	error	When
401	unauthorized	Missing or no Authorization header
401	invalid_key	API key not found or wrong secret
401	key_expired	API key past expiration date
403	insufficient_scope	Key doesn't have the required scope
403	plan_required	Effective plan doesn't support this action
403	insufficient_role	Team member/viewer cannot create scans
403	team_project_required	scan:create attempted on a personal project
404	not_found	Resource not found
409	scan_in_progress	A scan is already running for this project
429	rate_limit_exceeded	Rate limit exceeded (check Retry-After header)

Endpoints

GET/api/v1/projects

List all projects you own. Returns project name, GitHub URL, team, and timestamps.

Scope: project:read

curl -H "Authorization: Bearer vex_sk_xxx.yyy" \
  "https://vexlit.ai/api/v1/projects?limit=20&offset=0"

{
  "projects": [
    {
      "id": "f454d2c1-...",
      "name": "my-app",
      "github_url": "https://github.com/user/my-app",
      "team_id": "945927b0-...",
      "created_at": "2026-03-12T20:37:43Z"
    }
  ],
  "total": 1,
  "limit": 20,
  "offset": 0
}

POST/api/v1/scan

Create and queue a new scan for a team project. Returns immediately with scan ID.

Scope: scan:create | Plan: Team+ | Team projects only

curl -X POST -H "Authorization: Bearer vex_sk_xxx.yyy" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: ci-run-12345" \
  -d '{"project_id": "f454d2c1-..."}' \
  https://vexlit.ai/api/v1/scan

{
  "scan_id": "05243393-...",
  "status": "queued"
}

Scans run asynchronously. Poll GET /scans/:id to check status.

Use Idempotency-Key header to prevent duplicate scans on retry.

Returns 409 if the project already has a queued or running scan.

GET/api/v1/scans

List scans. Filter by project_id. Paginate with limit and offset.

Scope: scan:read

curl -H "Authorization: Bearer vex_sk_xxx.yyy" \
  "https://vexlit.ai/api/v1/scans?project_id=f454d2c1-...&limit=10&offset=0"

{
  "scans": [
    {
      "id": "de2ebc97-...",
      "project_id": "14f792b8-...",
      "status": "completed",
      "total_vulnerabilities": 68,
      "critical_count": 14,
      "high_count": 24,
      "medium_count": 19,
      "low_count": 11,
      "duration_ms": 20842,
      "created_at": "2026-03-17T02:30:26Z",
      "completed_at": "2026-03-17T02:30:47Z"
    }
  ],
  "total": 15,
  "limit": 10,
  "offset": 0
}

GET/api/v1/scans/:id

Get scan details with vulnerability list and severity summary. Paginate vulnerabilities with limit/offset.

Scope: scan:read

curl -H "Authorization: Bearer vex_sk_xxx.yyy" \
  "https://vexlit.ai/api/v1/scans/de2ebc97-...?limit=100&offset=0"

{
  "scan": { "id": "de2ebc97-...", "status": "completed", ... },
  "summary": { "critical": 14, "high": 24, "medium": 19, "low": 11, "total": 68 },
  "vulnerabilities": [
    {
      "id": "b463b031-...",
      "rule_id": "VEXLIT-003",
      "rule_name": "Cross-Site Scripting (XSS)",
      "severity": "critical",
      "message": "Express response HTML concatenation",
      "file_path": "src/server.js",
      "line": 37,
      "cwe": "CWE-79",
      "owasp": "A03:2021",
      "suggestion": "Sanitize user input before inserting into the DOM.",
      "confidence": "high",
      "reachable": true,
      "status": "open"
    }
  ],
  "total": 68,
  "limit": 100,
  "offset": 0
}

GET/api/v1/scans/:id/sarif

Download SARIF (Static Analysis Results Interchange Format) for a completed scan.

Scope: scan:read | Completed scans only

curl -H "Authorization: Bearer vex_sk_xxx.yyy" \
  "https://vexlit.ai/api/v1/scans/de2ebc97-.../sarif" -o results.sarif

Returns OASIS SARIF 2.1.0 format. Upload to GitHub Security tab or any SARIF-compatible tool.

GET/api/v1/projects/:id/vulns

Get vulnerabilities from the latest completed scan of a project. Filter by severity and status.

Scope: vuln:read

curl -H "Authorization: Bearer vex_sk_xxx.yyy" \
  "https://vexlit.ai/api/v1/projects/f454d2c1-.../vulns?severity=critical,high&status=open&limit=50&offset=0"

Filter: severity=critical,high (comma-separated). Default status: open.

Returns the latest completed scan's data. If no scans exist, returns empty array.

Rate Limiting

When rate limited, the response includes a Retry-After header and retry_after field in the body (seconds until reset).

HTTP/1.1 429 Too Many Requests
Retry-After: 3600

{
  "error": "rate_limit_exceeded",
  "message": "Too many requests. Upgrade plan for higher limits.",
  "retry_after": 3600
}

Idempotency

For POST /scan, include an Idempotency-Key header to prevent duplicate scans when retrying. If the same key is sent within 1 hour, the original scan ID is returned.

curl -X POST -H "Authorization: Bearer vex_sk_xxx.yyy" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: unique-build-id-12345" \
  -d '{"project_id": "f454d2c1-..."}' \
  https://vexlit.ai/api/v1/scan

Idempotency keys are scoped per API key and expire after 1 hour.

Auto-Fix PR Workflow

When used with a GitHub-connected project, VEXLIT can automatically fix vulnerabilities and create pull requests.

POST /scanScan completesVulnerabilities detectedAuto-Fix PR created

Auto-Fix PR is triggered from the dashboard after scan completion. The API triggers the scan; fix and PR creation happen automatically if enabled in project settings.