Skip to main content
REST API

Developers

Platform API

Programmatically manage projects, scans, findings, and reports. Integrate Nebula into your CI/CD pipeline and security workflows.

Auth
API key setup
Projects
Manage projects
Scans
Run security scans
Findings
Vulnerability data

Security

Authentication

Authenticate API requests using your API key or JWT token

Getting an API Key

  1. 1Log in to your BreachLine dashboard and go to Settings
  2. 2Navigate to API Keys section
  3. 3Click "Create API Key"
  4. 4Select required scopes
  5. 5Copy and securely store your key

Available Scopes

scans:*Full scan access
findings:readView findings
findings:writeUpdate findings
projects:*Full project access
assets:readView assets
reports:*Generate reports
llm:*Nebula LLM API access

Authentication Headers

# Authenticate with API Key
curl -X GET "https://api.breachline.io/api/v1/projects" \
  -H "X-API-Key: bl_live_xxxxxxxxxxxx" \
  -H "Content-Type: application/json"

# Or use Bearer token (JWT)
curl -X GET "https://api.breachline.io/api/v1/projects" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json"

Auth Endpoints

POST/api/v1/auth/register

Register a new user account

POST/api/v1/auth/login

Authenticate and get JWT tokens

POST/api/v1/auth/refresh

Refresh access token

POST/api/v1/auth/logout

Invalidate current session

GET/api/v1/auth/me

Get current user profile

POST/api/v1/auth/verify-email

Verify email address

POST/api/v1/auth/reset-password

Reset user password

Management

API Keys

Create and manage API keys programmatically

POST/api/v1/keys/create

Create new API key

GET/api/v1/keys/list

List all API keys

DELETE/api/v1/keys/{key_id}

Revoke API key

POST/api/v1/keys/refresh/{key_id}

Rotate API key

GET/api/v1/keys/usage

Get API key usage stats

Create API Key

curl -X POST "https://api.breachline.io/api/v1/keys/create" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "CI/CD Pipeline Key",
    "scopes": ["scans:*", "findings:read", "projects:read"],
    "expires_in_days": 90
  }'

# Response (key shown only once!)
{
  "id": "key_abc123",
  "name": "CI/CD Pipeline Key",
  "key": "bl_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "scopes": ["scans:*", "findings:read", "projects:read"],
  "created_at": "2026-01-15T10:00:00Z",
  "expires_at": "2026-04-15T10:00:00Z"
}

Resources

Projects

Organize security assessments into projects

GET/api/v1/projects

List all projects

POST/api/v1/projects

Create a new project

GET/api/v1/projects/{id}

Get project details

PUT/api/v1/projects/{id}

Update project

DELETE/api/v1/projects/{id}

Delete project

GET/api/v1/projects/{id}/scans

Get project scans

GET/api/v1/projects/{id}/findings

Get project findings

GET/api/v1/projects/{id}/team

Get project team members

POST/api/v1/projects/{id}/team

Add team member to project

GET/api/v1/projects/{id}/conversations

List project conversations

POST/api/v1/projects/{id}/conversations

Create new conversation

Create Project Example

curl -X POST "https://api.breachline.io/api/v1/projects" \
  -H "X-API-Key: bl_live_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Q1 2026 Security Audit",
    "description": "Comprehensive security assessment",
    "target_scope": ["*.example.com", "api.example.com"]
  }'

# Response
{
  "id": "proj_abc123",
  "name": "Q1 2026 Security Audit",
  "description": "Comprehensive security assessment",
  "target_scope": ["*.example.com", "api.example.com"],
  "created_at": "2026-01-15T10:00:00Z"
}

Core Feature

Scans

Run automated security scans against your targets

Scan Types
quick - Fast surface-level scan (5-10 min)
full - Comprehensive deep scan (1-4 hours)
stealth - Low-noise reconnaissance
targeted - Specific vulnerability checks
GET/api/v1/scans

List all scans (paginated)

POST/api/v1/scans

Create and start a new scan

GET/api/v1/scans/{id}

Get scan status and details

DELETE/api/v1/scans/{id}

Delete scan

GET/api/v1/scans/{id}/results

Get scan findings/results

GET/api/v1/scans/{id}/timeline

Get scan event timeline

GET/api/v1/scans/{id}/activity

Get scan activity log

POST/api/v1/scans/{id}/pause

Pause running scan

POST/api/v1/scans/{id}/resume

Resume paused scan

POST/api/v1/scans/{id}/stop

Stop running scan

POST/api/v1/scans/{id}/cancel

Cancel pending scan

GET/api/v1/scans/{id}/attack-graph

Get attack graph visualization

GET/api/v1/scans/{id}/entry-points

Get discovered entry points

GET/api/v1/scans/{id}/pocs

Get proof of concepts

GET/api/v1/scans/{id}/cost

Get scan LLM cost breakdown

POST/api/v1/scans/{id}/report/generate

Generate AI-powered report

GET/api/v1/scans/{id}/report/download

Download generated report

Start Scan

curl -X POST "https://api.breachline.io/api/v1/scans" \
  -H "X-API-Key: bl_live_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "target": "https://example.com",
    "scan_type": "full",
    "project_id": "proj_abc123",
    "config": {
      "depth": 3,
      "include_subdomains": true,
      "aggressive": false
    }
  }'

# Response
{
  "id": "scan_xyz789",
  "target": "https://example.com",
  "status": "pending",
  "scan_type": "full",
  "created_at": "2026-01-15T10:30:00Z"
}

Get Scan Status

curl -X GET "https://api.breachline.io/api/v1/scans/scan_xyz789" \
  -H "X-API-Key: bl_live_xxxxxxxxxxxx"

# Response
{
  "id": "scan_xyz789",
  "target": "https://example.com",
  "status": "running",
  "progress": 45,
  "scan_type": "full",
  "findings_count": 12,
  "assets_discovered": 28,
  "started_at": "2026-01-15T10:31:00Z",
  "estimated_completion": "2026-01-15T12:00:00Z"
}

Vulnerabilities

Findings

Access and manage discovered security vulnerabilities

Severity Levels
CRITICALHIGHMEDIUMLOWINFO
GET/api/v1/findings

List all findings (filterable)

GET/api/v1/findings/{id}

Get finding details

PATCH/api/v1/findings/{id}

Update finding status

DELETE/api/v1/findings/{id}

Delete finding

GET/api/v1/findings/{id}/comments

Get finding comments

POST/api/v1/findings/{id}/comments

Add comment to finding

Get Findings

curl -X GET "https://api.breachline.io/api/v1/findings?severity=critical,high&status=open" \
  -H "X-API-Key: bl_live_xxxxxxxxxxxx"

# Response
{
  "findings": [
    {
      "id": "find_001",
      "title": "SQL Injection in Login Form",
      "severity": "critical",
      "cvss_score": 9.8,
      "cwe_id": "CWE-89",
      "status": "open",
      "target": "https://example.com/login",
      "evidence": "Parameter 'username' is vulnerable...",
      "remediation": "Use parameterized queries...",
      "discovered_at": "2026-01-15T10:45:00Z"
    }
  ],
  "total": 5,
  "page": 1,
  "limit": 20
}

Discovery

Assets

Discovered subdomains, IPs, and services

GET/api/v1/assets

List all discovered assets

GET/api/v1/assets/{id}

Get asset details

POST/api/v1/assets

Create asset manually

PUT/api/v1/assets/{id}

Update asset

DELETE/api/v1/assets/{id}

Delete asset

GET/api/v1/assets/subdomains

List discovered subdomains

Integration

Python Example

Complete workflow example using Python

Full Scan Workflow

import requests
import time

API_KEY = "bl_live_xxxxxxxxxxxx"
BASE_URL = "https://api.breachline.io/api/v1"

headers = {
    "X-API-Key": API_KEY,
    "Content-Type": "application/json"
}

# Create a project
project = requests.post(
    f"{BASE_URL}/projects",
    headers=headers,
    json={
        "name": "Automated Scan",
        "description": "CI/CD security scan"
    }
).json()

# Start a scan
scan = requests.post(
    f"{BASE_URL}/scans",
    headers=headers,
    json={
        "target": "https://staging.example.com",
        "scan_type": "quick",
        "project_id": project["id"]
    }
).json()

# Poll for completion
while True:
    status = requests.get(
        f"{BASE_URL}/scans/{scan['id']}",
        headers=headers
    ).json()

    print(f"Progress: {status['progress']}%")

    if status["status"] in ["completed", "failed"]:
        break

    time.sleep(30)

# Get findings
findings = requests.get(
    f"{BASE_URL}/findings",
    headers=headers,
    params={
        "scan_id": scan["id"],
        "severity": "critical,high"
    }
).json()

# Generate report
report = requests.post(
    f"{BASE_URL}/scans/{scan['id']}/report/generate",
    headers=headers,
    json={"format": "pdf", "include_pocs": True}
).json()

print(f"Found {len(findings['findings'])} critical/high findings")

Usage

Rate Limits

API rate limits per key

60
req/min
1K
req/hour
10K
req/day

Need higher limits? Contact us for enterprise plans.

Get Started

Ready to Automate?

Create an API key and integrate Nebula into your workflow

Request Access View Nebula API