REST API Reference — Shieldome Docs

Authentication

All API requests must include your API key in the X-Shieldome-Key header. Generate keys in Account → API Keys.

bash

curl -H "X-Shieldome-Key: sk_live_xxxxxxxxxxxx" \
     https://yourdomain.com/api/scans

⚠️

Keep API keys secret. Never expose them in client-side code or public repositories.

Scans

POST /api/scan

Start a new scan.

request body

{
  "url":            "https://example.com",   // required
  "scan_type":      "both",                   // vuln | perf | both | api
  "target_ip":      "10.0.1.42",             // optional IP override
  "excluded_paths": ["/admin", "/logout"]    // optional
}

response

{ "scan_id": "uuid", "status": "running" }

Authentication & access control fields

Field	Type	Description
`auth_config`	object	Authentication configuration. Requires a `type` field. Cookie: `{"type":"cookie","cookie_string":"..."}`. Bearer token: `{"type":"token","token":"..."}`. Playwright form login: `{"type":"form","login_url":"...","username":"...","password":"...","success_url_contains":"..."}`. See Authenticated Scanning.
`custom_headers`	object	Additional HTTP headers sent with every request during the scan. Keys are header names, values are header values.
`excluded_paths`	array of strings	URL path prefixes to skip during crawling and scanning. E.g. `["/logout", "/admin/delete"]`.

Scan behaviour fields

Field	Type	Default	Description
`scan_speed`	string	`"normal"`	Scan speed mode: `"normal"`, `"cautious"`, or `"stealth"`. See Scan Speed & Stealth Mode.
`request_delay_ms`	integer	`0`	Fixed delay in milliseconds between requests, 0–5000. Overrides the speed mode's default delay.
`tags`	array of strings	`[]`	Labels attached to this scan for filtering. E.g. `["production", "sprint-42"]`.
`webhook_url`	string	null	URL to POST scan results to when the scan completes. See Webhooks.

GET /api/scan/{scan_id}

Get the status and full results of a scan. Poll this endpoint until status is completed or failed. While a scan is running, the results field is null.

response

{
  "id":               "a1b2c3d4-e5f6-...",
  "target_url":       "https://example.com",
  "target_ip":        null,               // IP override if set
  "scan_type":        "both",             // vuln | perf | both | api
  "status":           "completed",        // running | completed | failed
  "tags":             ["production"],
  "notes":            "",
  "scan_authorized":  true,
  "started_at":       "2026-06-14T10:00:00",
  "completed_at":     "2026-06-14T10:07:42",
  "summary": {
    "risk_score": 42,  // 0–100, higher = more risk
    "critical":   1,
    "high":       3,
    "medium":     5,
    "low":        2,
    "info":       1
  },
  "results": {
    "vulnerabilities": [    // array of finding objects (vuln/both/api scans)
      {
        "title":       "SQL Injection Indicator",
        "category":    "Injection",
        "owasp_id":    "A03:2021",
        "severity":    "critical",   // critical|high|medium|low|info
        "status":      "vulnerable", // vulnerable|safe|info
        "description": "Error-based SQL injection indicator detected.",
        "evidence":    "Response contained: You have an error in your SQL syntax",
        "remediation": "Use parameterised queries or prepared statements.",
        "cvss_score":  9.8,
        "cwe_id":      "CWE-89"
      }
    ],
    "performance": {         // present for both/perf scans; null otherwise
      "dns_ms":            12,
      "ttfb_ms":           210,
      "page_size_kb":      84,
      "http2":             true,
      "gzip":              true,
      "performance_score": 87
    },
    "tech_stack": ["nginx/1.24", "Django"]
  }
}

⚠️

Findings are always nested at results.vulnerabilities, not at the root level. Code that reads a top-level findings key will get undefined.

GET /api/scan/{scan_id}/progress

Server-Sent Events stream for real-time scan progress. Each event is a JSON object with type (progress/finding/done/error) and a data payload.

bash

curl -H "X-Shieldome-Key: YOUR_KEY" \
     -H "Accept: text/event-stream" \
     /api/scan/{scan_id}/progress

POST /api/scan/{scan_id}/abort

Gracefully stop a running scan.

DELETE /api/scan/{scan_id}

Delete a scan and its results from history.

GET /api/scans

List scans with optional filtering. Supports query parameters:

Parameter	Type	Description
`status`	string	`running`, `completed`, or `failed`
`search`	string	Filter by target URL substring
`tag`	string	Filter by tag label
`page`	int	Page number (default: 1)
`per_page`	int	Results per page, max 100 (default: 20)

response

{
  "items":    [...],   // array of scan objects (same shape as GET /api/scan/{id})
  "total":    47,
  "page":     1,
  "per_page": 20,
  "pages":    3
}

Developer API (v1)

The /api/v1/ prefix is the stable, versioned surface for CI/CD tools, the GitHub Action, and third-party integrations. Authentication is the same X-Shieldome-Key header.

ℹ️

These endpoints are an alias layer over the internal API. They return simplified payloads and will remain stable across minor releases.

POST /api/v1/scan

Trigger a new scan and get back a scan_id immediately. The scan runs asynchronously.

request body

{
  "url":       "https://example.com",  // required
  "scan_type": "vuln",               // vuln | perf | both
  "target_ip": "10.0.1.42"           // optional IP override
}

response — 202 Accepted

{
  "scan_id":   "a1b2c3d4-...",
  "status":    "running",
  "status_url": "/api/v1/scan/a1b2c3d4-...",
  "sarif_url":  "/api/v1/scan/a1b2c3d4-.../sarif"
}

GET /api/v1/scan/{scan_id}

Poll for scan status and results. Returns findings once status is completed.

response

{
  "id":          "a1b2c3d4-...",
  "target_url":  "https://example.com",
  "status":      "completed",   // running | completed | failed
  "summary": {
    "critical": 0, "high": 2, "medium": 5,
    "low": 1, "info": 3, "risk_score": 38
  },
  "findings": [...]   // null while running
}

GET /api/v1/scans

List the last 50 scans for the authenticated user, newest first.

GET /api/v1/scan/{scan_id}/sarif

Export findings as SARIF 2.1.0 — same as /api/scan/{id}/sarif, exposed here for GitHub Action compatibility.

Reports & Exports

GET /api/scan/{scan_id}/report

Download scan report as PDF. Returns application/pdf.

GET /api/scan/{scan_id}/docx

Download report as Word document (.docx).

GET /api/scan/{scan_id}/sarif

Export findings as SARIF 2.1.0 — for GitHub Advanced Security, Azure DevOps, and other compatible platforms.

GET /api/scans/export.csv

Export all scan findings as CSV — one row per finding across all scans.

POST /api/report/bulk

Generate a combined PDF for multiple scans. Body: {"scan_ids": ["id1","id2"]}.

Batch Jobs

POST /api/batch

Start a batch scan job for multiple targets.

request body

{
  "targets":   ["https://site1.com", "https://site2.com"],
  "scan_type": "both"
}

GET /api/batch/{batch_id}

Get batch job status and list of individual scan IDs.

Scheduled Scans

GET /api/schedules

List all scheduled scan configurations.

POST /api/schedules

request body

{
  "url":            "https://example.com",
  "scan_type":      "both",      // vuln | perf | both | api
  "interval_hours": 24          // number of hours between runs
}

DELETE /api/schedules/{id}

Delete a scheduled scan.