Vigolium API Reference, Ingestion

Import HTTP request/response data into the database for scanning via URLs, curl commands, HAR, OpenAPI, and more.

POST /api/ingest-http, Ingest HTTP Data

Import HTTP request/response data into the database for scanning. Supports multiple input formats.

Headers:

Header	Required	Description
Content-Type	Yes	Must be application/json
X-Project-UUID	No	Project UUID to scope the imported data. Falls back to the default project if omitted.
X-Vigolium-Source	No	The pushing tool: burp or caido. Anything else (or omitted) stores the record as ingest-server.

Declaring the pushing tool

Records ingested through this endpoint are stored with source: "ingest-server" by default — the same label every HTTP client shares. A client can name itself instead, so its traffic stays distinguishable later:

curl -s -X POST http://localhost:9002/api/ingest-http \
  -H "Content-Type: application/json" \
  -H "X-Vigolium-Source: caido" \
  -d '{"input_mode": "url", "content": "https://example.com/api/users?id=1"}' | jq .

Accepted values are burp and caido — the same labels the live bridge writes, so one ?source=caido filter covers traffic that arrived either by Vigolium pulling over the bridge or by the plugin pushing here. The Vigolium Burp extension and Caido plugin set it automatically.

The list is a closed allowlist, not a passthrough, and anything else falls back to ingest-server. source is not only a display label: it decides which rows scan-on-receive feeds back into a running scan, so a client free to claim scanner could silently exclude its own traffic from the scan it just asked for.

Request body:

Field	Type	Required	Description
input_mode	string	Yes	Input format (see modes below)
url	string	No	Override URL (used as base URL for some modes)
content	string	No	Raw content (plaintext)
content_base64	string	No	Base64-encoded content
http_request_base64	string	No	Base64-encoded raw HTTP request (for burp_base64)
http_response_base64	string	No	Base64-encoded raw HTTP response (for burp_base64)

Input modes:

Mode	Description	Content field
url	Single URL	content
url_file	Newline-separated list of URLs	content
curl	Single curl command	content
burp_base64	Base64 raw HTTP request (+response)	http_request_base64
openapi / swagger	OpenAPI/Swagger spec (JSON or YAML)	content
postman_collection	Postman Collection v2	content
har / http_archive	HAR (HTTP Archive) 1.2 JSON	content

Ingest a URL

curl -s -X POST http://localhost:9002/api/ingest-http \
  -H "Content-Type: application/json" \
  -d '{
    "input_mode": "url",
    "content": "https://example.com/api/users?id=1"
  }' | jq .

Ingest a curl command

curl -s -X POST http://localhost:9002/api/ingest-http \
  -H "Content-Type: application/json" \
  -d '{
    "input_mode": "curl",
    "content": "curl -X POST https://example.com/login -d \"user=admin&pass=test\""
  }' | jq .

Ingest a list of URLs

curl -s -X POST http://localhost:9002/api/ingest-http \
  -H "Content-Type: application/json" \
  -d '{
    "input_mode": "url_file",
    "content": "https://example.com/page1\nhttps://example.com/page2\nhttps://example.com/page3"
  }' | jq .

Ingest a raw HTTP request (base64)

# Base64-encode a raw HTTP request
REQ_B64=$(echo -n "GET /api/users HTTP/1.1\r\nHost: example.com\r\n\r\n" | base64)

curl -s -X POST http://localhost:9002/api/ingest-http \
  -H "Content-Type: application/json" \
  -d "{
    \"input_mode\": \"burp_base64\",
    \"http_request_base64\": \"$REQ_B64\"
  }" | jq .

Ingest a raw HTTP request with a URL hint (base64)

Raw HTTP requests don’t contain the scheme (https vs http) and the Host header alone may not reflect the actual target (e.g. behind a reverse proxy). Provide url alongside http_request_base64 so the parser can resolve the correct scheme and hostname.

REQ_B64=$(echo -n "POST /api/login HTTP/1.1\r\nHost: internal-lb\r\nContent-Type: application/json\r\n\r\n{\"user\":\"admin\"}" | base64)

curl -s -X POST http://localhost:9002/api/ingest-http \
  -H "Content-Type: application/json" \
  -d "{
    \"input_mode\": \"burp_base64\",
    \"url\": \"https://app.example.com\",
    \"http_request_base64\": \"$REQ_B64\"
  }" | jq .

The url field provides the scheme (https) and the public hostname (app.example.com), overriding whatever Host header appeared in the raw request.

Ingest a HAR file

curl -s -X POST http://localhost:9002/api/ingest-http \
  -H "Content-Type: application/json" \
  -d "{
    \"input_mode\": \"har\",
    \"content_base64\": \"$(base64 < recording.har)\"
  }" | jq .

Ingest an OpenAPI spec

curl -s -X POST http://localhost:9002/api/ingest-http \
  -H "Content-Type: application/json" \
  -d "{
    \"input_mode\": \"openapi\",
    \"content_base64\": \"$(base64 < openapi.json)\"
  }" | jq .

Response:

{
  "project_uuid": "default",
  "imported": 15,
  "skipped": 0,
  "errors": [],
  "message": "imported 15 requests from OpenAPI spec"
}

Ingest into a specific project

Use the X-Project-UUID header to scope imported data to a project. If omitted, data is stored under the default project.

curl -s -X POST http://localhost:9002/api/ingest-http \
  -H "Content-Type: application/json" \
  -H "X-Project-UUID: my-project-uuid" \
  -d '{
    "input_mode": "url",
    "content": "https://example.com/api/users"
  }' | jq .

{
  "project_uuid": "my-project-uuid",
  "imported": 1,
  "skipped": 0,
  "message": "imported 1 request from URL"
}

POST /api/burp/sitemap/snapshot, Ingest a Burp Site Map Snapshot

Uploads a chunk of a Burp Suite Target Site map snapshot into the database. This is the endpoint the companion burp-vigolium extension calls when you snapshot your Target Site map (Ctrl+Alt+S or periodic snapshots). Snapshots are chunked (a single site map is split across sequential requests), incremental within a Burp session, and idempotent on the server — unchanged records are never duplicated.

Headers:

Header	Required	Description
Authorization	Yes	Bearer <token> — requires operator (or admin) role
Content-Type	Yes	Must be application/json
X-Project-UUID	No	Project UUID to scope the imported records. Falls back to the default project if omitted.

Request body:

Field	Type	Required	Description
snapshot_id	string	Yes	Identifier for the snapshot the chunks belong to
chunk_index	int	Yes	Zero-based index of this chunk within the snapshot
final_chunk	bool	No	true on the last chunk of the snapshot
captured_at	string	No	Timestamp the snapshot was captured in Burp
records	array	Yes	Up to 200 site map records per chunk (see below)

Each entry in records:

Field	Type	Required	Description
url	string	No	Absolute URL — supplies the scheme and host the raw request lacks
request_base64	string	Yes	Base64-encoded raw HTTP request
response_base64	string	No	Base64-encoded raw HTTP response, when Burp captured one
identity_fingerprint	string	No	Extension-computed request-identity hash (drives dedup)
content_fingerprint	string	No	Extension-computed response-content hash (detects changed rows)

A chunk carrying more than 200 records is rejected with 400.

Upload a snapshot chunk

curl -s -X POST http://localhost:9002/api/burp/sitemap/snapshot \
  -H "Authorization: Bearer my-secret-key" \
  -H "Content-Type: application/json" \
  -d "{
    \"snapshot_id\": \"snap-2026-07-11T10-00-00\",
    \"chunk_index\": 0,
    \"final_chunk\": true,
    \"records\": [
      {
        \"url\": \"https://example.com/api/users\",
        \"request_base64\": \"$REQ_B64\",
        \"response_base64\": \"$RESP_B64\",
        \"identity_fingerprint\": \"a1b2c3\",
        \"content_fingerprint\": \"d4e5f6\"
      }
    ]
  }" | jq .

Response:

{
  "received": 1,
  "inserted": 1,
  "updated": 0,
  "unchanged": 0,
  "skipped": 0,
  "errors": []
}

Every record is upserted individually: inserted counts new rows, updated counts rows whose response changed, unchanged counts idempotent no-ops, and skipped counts records that failed to decode or parse (with the reason appended to errors). received is the number of records in the chunk.