Skip to main content

API Cookbook: Recipes

availability

Package: Invicti AppSec Core (on-demand)

This cookbook covers the most common Invicti AppSec API workflows: authenticating, setting up targets, launching scans, reviewing findings, and generating reports. Recipes are ordered so that IDs and tokens you capture in earlier steps feed directly into later ones, keeping everything on one page so you don't lose context as you work through a sequence.

If you're new to the Invicti API or building your first automation script, start here. For the complete API reference (all endpoints, parameters, and schemas), use the Swagger UI linked below. You can run both side by side: use the cookbook for guided sequences and Swagger to explore additional options or look up specific endpoints.

APIs used: Identity Management API · Inventory API · DAST API

Why this matters​

Automating the full security testing workflow through the API lets you integrate scanning directly into CI/CD pipelines, provision targets at scale, and feed machine-readable results into issue trackers or dashboards - without manual steps in the UI. This page walks you from your first authenticated call through creating a target, running a scan, reviewing findings, and generating a downloadable report.

⚙️ Your Configuration

Enter your credentials once - they will be substituted into every code example on this page.

Your initials (top right)  ›  User settings  ›  API key  ›  Copy to use existing, or Generate new API key

US: https://platform.invicti.com  ·  EU: https://platform-eu.invicti.com  ·  Canada: https://platform-ca.invicti.com  ·  On-premises: your own platform URL

On-premises deployments

The Execute in browser feature connects directly to platform.invicti.com and is available for on-demand accounts only. If you have an on-premises deployment, you can still use the code examples and request/response structures in these recipes — run them with your preferred API client (Postman, curl, and so on) against your own API endpoint.

Step 1
API fundamentals: get authenticated and make your first calls
🎯 GoalI want to verify my API key works, understand the response format, and explore my organization and workspace structure before building any automation.
Step 2
Configure a Target
🎯 GoalRegister a web application in the Invicti inventory, retrieve its target ID, and optionally select a scan profile before running any scans.
Step 3
Configure authentication (LSR) - optional
🎯 GoalYour target requires login to scan protected pages. Upload a Login Sequence Recorder file so the scanner can authenticate during the scan. Skip this journey if your target is publicly accessible.
Step 4
Launch & Monitor a Scan
🎯 GoalStart a security scan on a configured target and poll for completion. Once the scan finishes, capture the scan_session_id needed to retrieve results.
Step 5
Review Results & Generate a Report
🎯 GoalRetrieve the list of vulnerabilities found, inspect individual findings, and generate a downloadable security report once the scan is complete.
Step 6
Review vulnerabilities & results
🎯 GoalAfter a scan completes, retrieve the vulnerability findings, understand their severity, and analyze individual security issues in detail.
Step 7
Generate reports
🎯 GoalCreate comprehensive security reports for stakeholders in different formats (executive, developer, compliance) and download them as HTML or PDF.

Troubleshooting​

401 or 403 errors on every request

A 401 Unauthorized means your API key is missing or malformed. A 403 Forbidden means the key is valid but the account does not have permission for that endpoint.

  • Confirm the X-Auth header value is your full API key with no extra whitespace or quotes.
  • Check that the API key is not expired or revoked in Settings → API Keys.
  • For 403 errors, verify your user role has the required permissions. Target creation and scan launch require at minimum the User role; report generation may require Team Manager or higher depending on your plan.
  • If you are using a service account, ensure it has been assigned to the correct team that owns the target.
Scan is stuck in "queued" status

A scan stays in queued when no scan agent is available to pick it up.

  • Check that at least one scan agent is online and connected in Settings → Agents.
  • If you are running on-premises agents, verify the agent service is running and can reach platform.invicti.com on port 443.
  • Queued scans are processed in order. If many scans are queued, wait for earlier ones to complete or cancel lower-priority scans through the UI or via DELETE /api/v1/scans/{scanId}.
  • If the scan remains queued for more than 30 minutes with agents online, contact Invicti Support.
Report is stuck in "processing" status

Report generation is asynchronous and normally completes within a few minutes, but large scan results or high platform load can extend this.

  • Poll GET /api/v1/reports/{reportId} every 60 seconds rather than every few seconds to avoid rate limiting.
  • If status stays processing for more than 15 minutes, cancel the report request and resubmit. There is no cancel endpoint; delete the report via the UI and call POST /api/v1/reports again.
  • Ensure the scan_id passed to the report request belongs to a scan with status completed. Reports cannot be generated for scans that are still running or have failed.
  • If the status transitions to failed, check that the template_id is valid by calling GET /api/v1/report_templates and confirming the ID appears in the response.

Need help?​

Invicti Support team is ready to provide you with technical help. Go to Help Center

Was this page useful?