Curl

This page provides complete cURL examples for common S4E API operations. Replace YOUR_API_KEY with your actual API key in all examples.

Authenticate and Get a Session Token

curl -X POST "https://api.s4e.io/api/user/auth/login" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "password": "your-password",
    "captcha_response": "string",
    "bypass_captcha": false,
    "vendor": "googlev3"
  }'

Response:

{
  "status": "success",
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIs...",
    "user": {"id": 42, "email": "[email protected]", "role": "admin"}
  }
}

List Assets

curl -X GET "https://api.s4e.io/api/assets?type=domain&status=active&page=1&per_page=10" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response:

{
  "data": [
    {"id": "a-1001", "name": "example.com", "type": "domain", "status": "active", "risk_score": 72}
  ],
  "meta": {"total": 45, "page": 1, "per_page": 10}
}

Create an Asset

curl -X POST "https://api.s4e.io/api/assets" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "api.example.com",
    "type": "domain",
    "tags": ["production", "api"]
  }'

Response:

{
  "data": {
    "id": "a-1002",
    "name": "api.example.com",
    "type": "domain",
    "status": "pending_verification"
  }
}

Trigger a Scan

curl -X POST "https://api.s4e.io/api/scan/create" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "asset_id": "a-1001",
    "scan_type": "full",
    "options": {
      "depth": "deep",
      "include_subdomains": true
    }
  }'

Response:

{
  "data": {
    "scan_id": "sc-44021",
    "status": "queued",
    "estimated_duration_minutes": 15
  }
}

Check Scan Status

curl -X GET "https://api.s4e.io/api/scan/sc-44021/status" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response:

{
  "data": {
    "scan_id": "sc-44021",
    "status": "running",
    "progress": 65,
    "current_phase": "web_vulnerability_checks"
  }
}

Poll Until Scan Completes

while true; do
  status=$(curl -s "https://api.s4e.io/api/scan/sc-44021/status" \
    -H "Authorization: Bearer YOUR_API_KEY" | python3 -c "
import sys, json
print(json.load(sys.stdin)['data']['status'])")

  echo "Scan status: $status"

  if [ "$status" = "completed" ] || [ "$status" = "failed" ]; then
    break
  fi

  sleep 10
done

List Findings (Filtered by Severity)

curl -X GET "https://api.s4e.io/api/findings?severity=critical,high&status=open&sort_by=cvss&sort_order=desc" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response:

{
  "data": [
    {
      "id": "f-91827",
      "title": "SQL Injection in /api/login",
      "severity": "critical",
      "cvss": 9.8,
      "status": "open",
      "asset": {"id": "a-1001", "name": "api.example.com"}
    }
  ],
  "meta": {"total": 23, "page": 1, "per_page": 20}
}

Get Finding Details

curl -X GET "https://api.s4e.io/api/findings/f-91827" \
  -H "Authorization: Bearer YOUR_API_KEY"

Update Finding Status

curl -X PUT "https://api.s4e.io/api/findings/f-91827/status" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "confirmed",
    "note": "Verified via manual penetration testing."
  }'

Export Findings to CSV

curl -X POST "https://api.s4e.io/api/findings/export" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"format": "csv", "filters": {"severity": "critical,high"}}' \
  -o findings.csv

Trigger an Action

curl -X POST "https://api.s4e.io/api/actions/act-block-ip/trigger" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "target": "a-1001",
    "parameters": {
      "ip_address": "203.0.113.50",
      "duration_hours": 24
    }
  }'

Response:

{
  "data": {
    "execution_id": "exec-9912",
    "status": "running"
  }
}

Check Action Execution Status

curl -X GET "https://api.s4e.io/api/actions/executions/exec-9912" \
  -H "Authorization: Bearer YOUR_API_KEY"

Run a Playbook

curl -X POST "https://api.s4e.io/api/playbooks/pb-critical-vuln-response/run" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "target_asset_id": "a-1001",
    "parameters": {},
    "dry_run": false
  }'

Response:

{
  "data": {
    "execution_id": "pexec-7721",
    "status": "running"
  }
}

Create a Webhook

curl -X POST "https://api.s4e.io/api/webhooks" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Slack Alerts",
    "url": "https://hooks.slack.com/services/T00/B00/xxx",
    "events": ["finding.new", "scan.completed"],
    "secret": "whsec_my_secret",
    "active": true
  }'

Bulk Import Assets

curl -X POST "https://api.s4e.io/api/assets/bulk" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "assets": [
      {"name": "app1.example.com", "type": "domain", "tags": ["production"]},
      {"name": "app2.example.com", "type": "domain", "tags": ["staging"]},
      {"name": "10.0.1.0/24", "type": "network", "tags": ["internal"]}
    ]
  }'

List API Keys

curl -X GET "https://api.s4e.io/api/keys" \
  -H "Authorization: Bearer YOUR_API_KEY"

Using jq for JSON Processing

Combine cURL with jq for powerful command-line workflows:

# Get all critical finding titles
curl -s "https://api.s4e.io/api/findings?severity=critical" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  | jq -r '.data[].title'

# Count findings by severity
curl -s "https://api.s4e.io/api/findings/stats" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  | jq '.data.by_severity'

# Get asset names with high risk scores
curl -s "https://api.s4e.io/api/assets?sort_by=risk_score&sort_order=desc&per_page=5" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  | jq -r '.data[] | "\(.name): \(.risk_score)"'

Tip

Save your API key in an environment variable to avoid repeating it: export S4E_KEY="your-key", then use -H "Authorization: Bearer $S4E_KEY" in all commands.

Next Steps