Skip to content

API reference

Vex Raptor exposes a versioned REST API under /api/v1. All business endpoints require a JWT bearer token unless noted; pentest scans stream results over Server-Sent Events (SSE).

Authoritative reference

The live, always-accurate API reference is the built-in OpenAPI/Swagger UI at /api/docs (and the raw spec at /api/openapi.json) on your deployment. This page is an orientation map; generate client code from the OpenAPI spec.

Authentication

# 1. Log in → receive a JWT (2-hour expiry)
curl -s -X POST https://<host>/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"you@company.com","password":"..."}'

# 2. Use the token on subsequent calls
curl -s https://<host>/api/v1/auth/me \
  -H "Authorization: Bearer <JWT>"

Tokens carry sub, role, org_id, and a jti that is checked against a revocation list on every request. Logout invalidates the token.

Key endpoint groups

Prefix / route Purpose
/api/v1/auth login, logout, me, SSO/OIDC flow
POST /api/v1/pentest/scan-stream Primary pentest SSE stream (JWT)
POST /api/v1/webhook/scan CI Gate — org API key (X-Vex-Key), pass/fail verdict
/api/v1/security Raptor/arsenal scan management and playbooks
/api/v1/api-scanner Dedicated OpenAPI-driven scans
/api/v1/reports Report retrieval, export, compliance PDF per scan
/api/v1/asm Attack-surface monitoring
/api/v1/intelligence Cross-intel; GET …/compliance for org posture
/api/v1/orgs Organizations and API keys
/api/v1/dashboard Aggregated posture for the dashboard
/api/v1/triggers Rules engine (CI Gate UI lives under Triggers)
/health Liveness probe (unversioned, no JWT)

The exact routes, parameters, and schemas are in the OpenAPI spec on your instance — treat that as the source of truth.

Streaming a pentest (SSE)

curl -N -X POST https://<host>/api/v1/pentest/scan-stream \
  -H "Authorization: Bearer <JWT>" \
  -H "Content-Type: application/json" \
  -d '{"target":"https://app.example.com","depth":"full"}'

Optional auth object: token, header_name/header_value, or login_url + username + password (+ field names).

Events: start first, tool_status and findings as phases run, terminal complete with total_findings, severity counts, risk_score, phases_completed, and attack_chains.

CI webhook (API key)

curl -sS -X POST https://<host>/api/v1/webhook/scan \
  -H "Content-Type: application/json" \
  -H "X-Vex-Key: <org-api-key>" \
  -d '{"target":"https://staging.example.com","fail_on":"high"}'

fail_on: critical | high | medium | never. Response includes a verdict of pass or fail. See CI Gate.

Rate limits & quotas

  • Login is rate-limited (per IP/user).
  • Each organization has a daily scan quota by plan, enforced atomically (HTTP 429 when exceeded).
  • Some features are gated by plan (HTTP 403 below the required plan).