Quick Start Guide

How to Discover APIs with Vespasian

Vespasian discovers API endpoints by observing real HTTP traffic. This guide covers the fastest ways to get started.

Quick Start: Scan a Web Application

The scan command crawls a target and generates a specification in one step:

# Crawl and generate an API spec (auto-detects API type)
vespasian scan https://app.example.com -o api.yaml

# With authentication
vespasian scan https://app.example.com -H "Authorization: Bearer <token>" -o api.yaml

# Specify the API type explicitly
vespasian scan https://app.example.com --api-type graphql -o schema.graphql

Two-Stage Workflow

For more control, separate capture from generation:

Stage 1: Capture Traffic

# Via headless browser
vespasian crawl https://app.example.com -o capture.json

# Or import from Burp Suite
vespasian import burp traffic.xml -o capture.json

# Or import from HAR archive
vespasian import har recording.har -o capture.json

# Or import from mitmproxy
vespasian import mitmproxy flows -o capture.json

Stage 2: Generate Specifications

# Generate OpenAPI spec for REST
vespasian generate rest capture.json -o api.yaml

# Generate GraphQL SDL schema
vespasian generate graphql capture.json -o schema.graphql

# Generate WSDL from SOAP traffic
vespasian generate wsdl capture.json -o service.wsdl

Common Options

# Route crawl traffic through Burp Suite
vespasian scan https://app.example.com --proxy http://127.0.0.1:8080 -o api.yaml

# Scan a local/private target (bypasses SSRF protection)
vespasian scan http://localhost:3000 --dangerous-allow-private -o api.yaml

# Verbose output to see discovered requests in real-time
vespasian scan https://app.example.com -v -o api.yaml

# Suppress the startup banner
vespasian --no-banner scan https://app.example.com -o api.yaml

Next Steps

• CLI Reference — Full command and flag reference
• Traffic Import Guide — Detailed import instructions for Burp, HAR, and mitmproxy
• Use Cases — Real-world scenarios