API Reference / v1.0

API Reference

The Auto Offensive REST API lets you programmatically manage projects, trigger scan jobs, retrieve results, and generate reports. Integrate security scanning into your CI/CD pipeline or internal tooling.

Security

Bearer Auth

Format

REST / JSON

Version

Stable v1

Access

Team Plan

Updated

March 2025

Format

REST / JSON

Access

Team Plan

Overview

REST API

All API requests are made to the base URL below. The API returns JSON for all responses. Authentication is required for every request using an API key passed in the request header.

Base URL

Base URL   https://api.autooffensive.com/v1

// All responses are returned as JSON.
// All requests must include the Authorization header.

API Key Authentication

Every request must include a valid bearer token in the Authorization header before the backend will process it.

Required

JSON Request and Response Format

Request payloads use application/json and every successful or error response returns structured JSON for easy automation.

JSON

Authentication

Auto Offensive uses API key authentication. Generate your key from Settings - API Keys. Pass the key in every request using the Authorization header.

Request Header

Authorization: Bearer aof_live_xxxxxxxxxxxxxxxxxxxx
Content-Type: application/json

WARNKeep your key secret

Never expose your API key in client-side code or public repositories. If compromised, rotate it immediately from Settings - API Keys. Keys do not expire but can be revoked at any time.

Rate Limits

API rate limits apply per API key per day. Scan jobs also count against your plan's daily scan quota. If you exceed the limit, requests return 429 Too Many Requests.

INFORate limit headers

Every response includes X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers so you can track usage programmatically.

Error Codes

All errors return a JSON body with a code and message field describing what went wrong.

HTTP Status	Code	Meaning
400	ERR_INVALID_PARAM	Missing or invalid request parameters
401	ERR_AUTH_FAILED	Missing or invalid API key
403	ERR_FORBIDDEN	Plan does not allow this action
404	ERR_NOT_FOUND	Project, scan, or report does not exist
429	ERR_QUOTA_EXCEEDED	Daily request or scan limit reached
500	ERR_SERVER_ERROR	Internal server error - try again later

Error Response Example

{
  "code": "ERR_QUOTA_EXCEEDED",
  "message": "Daily scan limit reached. Resets at 00: 00 UTC.",
  "status": 429
}

Projects

Endpoints

Projects are the top-level container for all scan jobs, results, and reports. All scan activity must belong to a project.

GET/projects

Auth RequiredAll Plans

Returns a list of all projects in your workspace, ordered by creation date (newest first).

Response

{
  "projects": [
    {
      "id": "proj_01HX...",
      "name": "ACME Corp - Q2 Assessment",
      "created_at": "2025-03-10T08: 30: 00Z",
      "scan_count": 14
    }
  ]
}

POST/projects

Auth Required

Creates a new project in your workspace.

Body Parameters

Parameter	Type	Required	Description
name	string	required	Name of the project (e.g. "ACME Corp Q2 Pentest")
description	string	optional	Short description of the engagement scope

Request / Response

// Request body
{
  "name": "ACME Corp - Q2 Assessment",
  "description": "Full-scope web and network pentest"
}

// Response 201
{
  "id": "proj_01HX...",
  "name": "ACME Corp - Q2 Assessment",
  "created_at": "2025-03-10T08: 30: 00Z"
}

GET/projects/{project_id}

Auth Required

Returns details of a single project including scan count and last activity timestamp.

Response

{
  "id": "proj_01HX...",
  "name": "ACME Corp - Q2 Assessment",
  "description": "Full-scope web and network pentest",
  "scan_count": 14,
  "created_at": "2025-03-10T08: 30: 00Z",
  "last_scan_at": "2025-03-14T11: 20: 00Z"
}

DELETE/projects/{project_id}

Auth Required

Permanently deletes a project and all associated scan jobs, results, and reports. This action cannot be undone.

Response 200

{ "deleted": true, "id": "proj_01HX..." }

WARNIrreversible

Deleting a project also deletes all scan results and generated reports inside it. There is no recovery.

Scan Jobs

Endpoints

Scan jobs represent a single scan execution against a target using one or more modules. All scan jobs belong to a project.

POST/projects/{project_id}/scans

Auth RequiredTeam Plan

Creates and immediately starts a new scan job. The job transitions to running status on creation.

Body Parameters

Parameter	Type	Required	Description
target	string	required	Domain, URL, or IP address to scan
modules	array	required	One or more module names: `subfinder` `nmap` `nuclei` `httpx` `sqli` and more
config	object	optional	Per-module configuration options (port range, wordlist, threads, etc.)
pipeline	boolean	optional	If `true`, runs modules sequentially, passing output to the next module

Request / Response

// Request body
{
  "target": "example.com",
  "modules": ["subfinder", "httpx", "nuclei"],
  "pipeline": true,
  "config": {
    "nuclei": { "severity": "critical,high" }
  }
}

// Response 201
{
  "scan_id": "scan_02KY...",
  "status": "running",
  "target": "example.com",
  "modules": ["subfinder", "httpx", "nuclei"],
  "created_at": "2025-03-14T09: 00: 00Z"
}

GET/projects/{project_id}/scans

Auth Required

Returns all scan jobs within a project, ordered by creation date. Supports filtering by status.

Query Parameters

Parameter	Type	Required	Description
status	string	optional	Filter by status: `running` `completed` `failed` `cancelled`
limit	integer	optional	Number of results to return (default: 20, max: 100)

GET/scans/{scan_id}

Auth Required

Returns the current status and metadata of a single scan job. Poll this endpoint to track progress of a running scan.

Response

{
  "scan_id": "scan_02KY...",
  "status": "completed",
  "target": "example.com",
  "modules": ["subfinder", "httpx", "nuclei"],
  "finding_count": 22,
  "started_at": "2025-03-14T09: 00: 00Z",
  "completed_at": "2025-03-14T09: 04: 12Z"
}

TIPPolling tip

Poll /scans/{id} every 5 seconds while status is running. When status changes to completed or failed, stop polling and fetch results.

POST/scans/{scan_id}/stop

Auth Required

Cancels a running scan job. Partial results collected up to the stop point are saved and accessible. Returns an error if the scan is already completed or failed.

Response 200

{ "scan_id": "scan_02KY...", "status": "cancelled" }

POST/scans/{scan_id}/retry

Auth Required

Re-runs a failed or cancelled scan job using the same target, modules, and configuration. A new scan_id is returned for the new job.

Response 201

{
  "scan_id": "scan_03LZ...",
  "status": "running",
  "retried_from": "scan_02KY..."
}

Results

Endpoints

Retrieve structured findings from a completed scan job. Results are linked to the scan and stored indefinitely.

GET/scans/{scan_id}/results

Auth Required

Returns all structured findings from a completed scan job - discovered assets, open ports, vulnerabilities, and identified issues.

Query Parameters

Parameter	Type	Required	Description
type	string	optional	Filter by finding type: `asset` `port` `vulnerability` `endpoint`
severity	string	optional	Filter vulnerabilities by severity: `critical` `high` `medium` `low`

Response

{
  "scan_id": "scan_02KY...",
  "total": 22,
  "results": [
    {
      "type": "vulnerability",
      "title": "SQL Injection - /api/users?id=",
      "severity": "critical",
      "cvss": 9.8,
      "tool": "nuclei",
      "evidence": "Error-based SQLi confirmed via time-delay"
    },
    {
      "type": "asset",
      "value": "api.example.com",
      "tool": "subfinder"
    }
  ]
}

Reports

Endpoints

Generate, list, and download security reports from completed scan jobs. Reports can be exported in PDF, DOCX, Excel, or JSON.

POST/scans/{scan_id}/reports

Auth RequiredTeam Plan

Generates a security report from a completed scan. AI writes the executive summary and remediation guidance automatically.

Body Parameters

Parameter	Type	Required	Description
template	string	required	executive technical developer compliance
format	string	required	pdf docx excel json
company_name	string	optional	Company name shown on the report cover page
compliance	string	optional	pci_dss iso_27001 soc2 nist

Request / Response

// Request body
{
  "template": "technical",
  "format": "pdf",
  "company_name": "ACME Corp",
  "compliance": "pci_dss"
}

// Response 201
{
  "report_id": "rpt_04MN...",
  "status": "generating",
  "format": "pdf",
  "template": "technical"
}

AIAI Report Writing

Report generation is asynchronous. Poll /reports/{report_id} until status is ready, then call the download endpoint. AI writing typically takes 10-30 seconds.

GET/projects/{project_id}/reports

Auth Required

Returns all generated reports linked to a project. Includes report status, template type, format, and generation timestamp.

Response

{
  "reports": [
    {
      "report_id": "rpt_04MN...",
      "scan_id": "scan_02KY...",
      "template": "technical",
      "format": "pdf",
      "status": "ready",
      "created_at": "2025-03-14T09: 10: 00Z"
    }
  ]
}

GET/reports/{report_id}/download

Auth Required

Returns a short-lived signed download URL for the generated report file. The URL expires after 15 minutes. Only available when report status is ready.

Response

{
  "report_id": "rpt_04MN...",
  "download_url": "https://cdn.autooffensive.com/reports/rpt_04MN...pdf?token=...",
  "expires_at": "2025-03-14T09: 25: 00Z",
  "format": "pdf"
}

Issues

Endpoints

Retrieve the detailed list of vulnerabilities and issues found during your scans.

GET/scans/{scan_id}/issues

Auth Required

Fetch the detailed list of vulnerabilities found during a scan. Can be filtered by severity.

Query Parameters

Parameter	Type	Required	Description
severity	string	optional	Filter by severity: `critical` `high` `medium` `low`
cursor	string	optional	Pagination cursor for fetching the next page

Response

{
  "data": [
    {
      "id": "issue_987",
      "severity": "high",
      "type": "SQL Injection",
      "file": "src/db/queries.ts",
      "line": 42,
      "description": "Unsanitized input passed directly to SQL execution context."
    }
  ],
  "meta": {
    "next_cursor": null
  }
}

AI Analysis

Endpoints

Interact with the AI engine for vulnerability remediation suggestions.

POST/issues/{issue_id}/remediate

Auth RequiredTeam Plan

Ask the AI engine to generate a fix for a specific issue.

Response

{
  "issue_id": "issue_987",
  "suggestion": "Use parameterized queries to prevent SQL injection.",
  "code_snippet": "const query = 'SELECT * FROM users WHERE id = $1';\nawait db.query(query, [userId]);"
}

Webhooks

Endpoints

POST/projects/{project_id}/webhooks

Auth Required

Create a new webhook to receive payloads when specific events occur.

Body Parameters

Parameter	Type	Required	Description
url	string	required	The destination URL that will receive POST requests
events	array	required	Array of events like: `scan.completed` `scan.failed` `report.ready`
secret	string	optional	Secret key for verifying payload signatures

Request / Response

// Request
{
  "url": "https://your-domain.com/webhooks/aof",
  "events": ["scan.completed", "report.ready"],
  "secret": "wh_secret_xyz123"
}

// Response 201
{
  "webhook_id": "wh_05OP...",
  "status": "active"
}

CLI Reference

CI/CD Integration

API Reference

Security

Bearer Auth

Format

REST / JSON

Version

Stable v1

Access

Team Plan

Updated

March 2025

Format

REST / JSON

Access

Team Plan

HTTP Status

Code

Meaning

400

ERR_INVALID_PARAM

Missing or invalid request parameters

401

ERR_AUTH_FAILED

Missing or invalid API key

403

ERR_FORBIDDEN

Plan does not allow this action

404

ERR_NOT_FOUND

Project, scan, or report does not exist

429

ERR_QUOTA_EXCEEDED

Daily request or scan limit reached

500

ERR_SERVER_ERROR

Internal server error - try again later

Parameter

Type

Required

Description

name

string

required

Name of the project (e.g. "ACME Corp Q2 Pentest")

description

string

optional

Short description of the engagement scope

Parameter

Type

Required

Description

target

string

required

Domain, URL, or IP address to scan

modules

array

required

One or more module names: subfinder nmap nuclei httpx sqli and more

config

object

optional

Per-module configuration options (port range, wordlist, threads, etc.)

pipeline

boolean

optional

If true, runs modules sequentially, passing output to the next module

Parameter

Type

Required

Description

status

string

optional

Filter by status: running completed failed cancelled

limit

integer

optional

Number of results to return (default: 20, max: 100)

Parameter

Type

Required

Description

type

string

optional

Filter by finding type: asset port vulnerability endpoint

severity

string

optional

Filter vulnerabilities by severity: critical high medium low

Parameter

Type

Required

Description

template

string

required

executive technical developer compliance

format

string

required

pdf docx excel json

company_name

string

optional

Company name shown on the report cover page

compliance

string

optional

pci_dss iso_27001 soc2 nist

Parameter

Type

Required

Description

severity

string

optional

Filter by severity: critical high medium low

cursor

string

optional

Pagination cursor for fetching the next page

Parameter

Type

Required

Description

url

string

required

The destination URL that will receive POST requests

events

array

required

Array of events like: scan.completed scan.failed report.ready

secret

string

optional

Secret key for verifying payload signatures