Skip to main content
Version: Next 🚧

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​

StatusMeaning
queuedAccepted, waiting for scanner capacity
runningScanner is actively executing
completedFinished successfully — results available
failedEncountered a fatal error
cancelledCancelled 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:

Pro Tip

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