Getting Started

Submit your first vulnerability scan in under 5 minutes. This guide walks you through obtaining an API key, submitting a scan, checking its status, and retrieving results.

Prerequisites

Before you begin, ensure you have:

• ✅ An active Cert-IX account with Scan API access
• ✅ Access to the Cert-IX Dashboard for API key management
• ✅ cURL or any HTTP client (Python requests, Postman, etc.)

Step 1: Get Your API Key

1. Log in to the Cert-IX Dashboard
2. Navigate to Settings → API Keys
3. Click Create API Key
4. Configure the key:
   • Name: Give it a descriptive name (e.g., "My First Scan Key")
   • Scopes: Select at least scans:create, scans:read, results:read
   • Expiration: Set an appropriate expiration (e.g., 90 days)
5. Click Create and copy the key immediately

Important

The raw API key is shown only once at creation time. Store it securely in a password manager or secrets vault. Cert-IX cannot retrieve it later.

Set the key as an environment variable for convenience:

export CERTIX_API_KEY="cix_sk_your_api_key_here"

Step 2: Submit Your First Scan

Let's run a basic Nmap network scan against a target:

curl -X POST https://api.cert-ix.com/scan-api/api/v1/scans \
  -H "X-API-Key: $CERTIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "target": "example.com",
    "scanType": "nmap",
    "name": "My First Scan",
    "options": {
      "ports": "1-1024",
      "timing": "T3",
      "serviceDetection": true
    }
  }'

Response:

{
  "success": true,
  "data": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "scanType": "nmap",
    "name": "My First Scan",
    "target": "example.com",
    "status": "queued",
    "priority": "normal",
    "progress": 0,
    "createdAt": "2026-03-06T10:00:00Z"
  }
}

Save the Scan ID

Copy the id from the response — you'll need it to check status and retrieve results.

export SCAN_ID="a1b2c3d4-e5f6-7890-abcd-ef1234567890"

Step 3: Check Scan Status

Scans run asynchronously. Poll the status endpoint to track progress:

curl -X GET "https://api.cert-ix.com/scan-api/api/v1/scans/$SCAN_ID?scanType=nmap" \
  -H "X-API-Key: $CERTIX_API_KEY"

Response (running):

{
  "success": true,
  "data": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "status": "running",
    "progress": 67
  }
}

Response (completed):

{
  "success": true,
  "data": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "status": "completed",
    "progress": 100,
    "resultCount": 12,
    "durationMs": 135000
  }
}

Status Values

Status	Meaning
queued	Accepted, waiting for scanner capacity
running	Scanner is actively executing
completed	Finished successfully — results available
failed	Encountered a fatal error
cancelled	Cancelled by user

Step 4: Retrieve Results

Once the scan status is completed, fetch the full results:

curl -X GET "https://api.cert-ix.com/scan-api/api/v1/scans/$SCAN_ID/results?scanType=nmap" \
  -H "X-API-Key: $CERTIX_API_KEY"

Response:

{
  "success": true,
  "data": {
    "scanId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "scanType": "nmap",
    "target": "example.com",
    "status": "completed",
    "results": {
      "hosts": [
        {
          "ip": "93.184.216.34",
          "hostname": "example.com",
          "state": "up",
          "ports": [
            {
              "port": 80,
              "protocol": "tcp",
              "state": "open",
              "service": "http",
              "version": "nginx 1.25.4"
            },
            {
              "port": 443,
              "protocol": "tcp",
              "state": "open",
              "service": "https",
              "version": "nginx 1.25.4"
            }
          ]
        }
      ],
      "stats": {
        "hostsUp": 1,
        "openPorts": 2,
        "closedPorts": 1022
      }
    }
  }
}

Complete Script

Here's a full Bash script that automates the entire workflow:

#!/bin/bash
# Cert-IX Scan API — Complete scan workflow
set -euo pipefail

API_KEY="${CERTIX_API_KEY:?Set CERTIX_API_KEY environment variable}"
BASE_URL="https://api.cert-ix.com/scan-api/api/v1"
TARGET="${1:-example.com}"

echo "🔍 Submitting Nmap scan for: $TARGET"

# Step 1: Submit scan
RESPONSE=$(curl -s -X POST "$BASE_URL/scans" \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d "{
    \"target\": \"$TARGET\",
    \"scanType\": \"nmap\",
    \"name\": \"Quick scan - $TARGET\",
    \"options\": {
      \"ports\": \"1-1024\",
      \"timing\": \"T3\",
      \"serviceDetection\": true
    }
  }")

SCAN_ID=$(echo "$RESPONSE" | jq -r '.data.id')
echo "✅ Scan submitted: $SCAN_ID"

# Step 2: Poll until complete
echo "⏳ Waiting for scan to complete..."
while true; do
  STATUS_RESP=$(curl -s -X GET "$BASE_URL/scans/$SCAN_ID?scanType=nmap" \
    -H "X-API-Key: $API_KEY")
  STATUS=$(echo "$STATUS_RESP" | jq -r '.data.status')
  PROGRESS=$(echo "$STATUS_RESP" | jq -r '.data.progress')

  echo "   Status: $STATUS ($PROGRESS%)"

  case "$STATUS" in
    completed) break ;;
    failed)    echo "❌ Scan failed"; exit 1 ;;
    cancelled) echo "⚠️ Scan cancelled"; exit 1 ;;
  esac

  sleep 5
done

# Step 3: Get results
echo "📊 Retrieving results..."
curl -s -X GET "$BASE_URL/scans/$SCAN_ID/results?scanType=nmap" \
  -H "X-API-Key: $API_KEY" | jq .

echo "✨ Done!"

What's Next?

Now that you've completed your first scan, explore these topics:

• Authentication & API Keys — Scopes, rotation, IP allowlisting
• Submitting Scans — All 10 engines with detailed options
• Webhooks — Real-time notifications instead of polling
• Code Examples — Production-ready Python, Go, and Node.js clients

Pro Tip

For production integrations, use webhooks instead of polling. Webhooks deliver instant notifications and consume zero API quota for status checks.