cURL recipes

Prefer a GUI? Download the Postman collection — auto-generated from the live OpenAPI spec, ready to import.

Set PENTIFY_API_KEY first:

export PENTIFY_API_KEY="pt_live_..."

Smoke test

curl https://api.pentify.io/v1/usage \
  -H "Authorization: Bearer $PENTIFY_API_KEY"

Register and verify a target

TARGET_ID=$(curl -s https://api.pentify.io/v1/targets \
  -H "Authorization: Bearer $PENTIFY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"hostname":"example.com"}' | jq -r .id)

curl -X POST "https://api.pentify.io/v1/targets/$TARGET_ID/verify" \
  -H "Authorization: Bearer $PENTIFY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"method":"dns"}'

Create a scan and poll until done

SCAN_ID=$(curl -s https://api.pentify.io/v1/scans \
  -H "Authorization: Bearer $PENTIFY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"target":"example.com","scan_type":"quick"}' \
  | jq -r .id)

while :; do
  STATUS=$(curl -s "https://api.pentify.io/v1/scans/$SCAN_ID" \
    -H "Authorization: Bearer $PENTIFY_API_KEY" | jq -r .status)
  case "$STATUS" in
    queued|running) sleep 5 ;;
    *) echo "$STATUS"; break ;;
  esac
done

Bulk scan (queue many in one call)

curl -X POST https://api.pentify.io/v1/scans/bulk \
  -H "Authorization: Bearer $PENTIFY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: ci-$(date +%s)" \
  -d '{
    "scans": [
      {"target":"example.com",       "scan_type":"quick"},
      {"target":"api.example.com",   "scan_type":"standard"},
      {"target":"admin.example.com", "scan_type":"compliance"}
    ],
    "fail_fast": false
  }' | jq '.summary, (.results[] | {ok, code: .error.code, id: .scan.id})'

Returns 201 with per-entry results[] in request order. Set fail_fast: true to roll back the whole batch on the first failure.

Cancel a scan

curl -X POST "https://api.pentify.io/v1/scans/$SCAN_ID/cancel" \
  -H "Authorization: Bearer $PENTIFY_API_KEY"

Pull the JSON report and the PDF

curl "https://api.pentify.io/v1/scans/$SCAN_ID/report" \
  -H "Authorization: Bearer $PENTIFY_API_KEY" \
  -o report.json

curl -L "https://api.pentify.io/v1/scans/$SCAN_ID/report.pdf" \
  -H "Authorization: Bearer $PENTIFY_API_KEY" \
  -o report.pdf

List critical findings only

curl "https://api.pentify.io/v1/scans/$SCAN_ID/findings?severity=critical" \
  -H "Authorization: Bearer $PENTIFY_API_KEY" | jq .

Subscribe to webhooks

curl https://api.pentify.io/v1/webhooks \
  -H "Authorization: Bearer $PENTIFY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/pentify-hook",
    "events": ["scan.completed", "scan.failed"]
  }'

Save the whsec_* secret returned — see Webhooks for verification.

Inspect token consumption

curl https://api.pentify.io/v1/usage \
  -H "Authorization: Bearer $PENTIFY_API_KEY" \
  | jq .last_30d.by_operation

Walk paginated lists

CURSOR=""
while :; do
  RES=$(curl -s "https://api.pentify.io/v1/scans?limit=100&cursor=$CURSOR" \
    -H "Authorization: Bearer $PENTIFY_API_KEY")
  echo "$RES" | jq -c '.data[]'
  CURSOR=$(echo "$RES" | jq -r '.next_cursor // empty')
  [ -z "$CURSOR" ] && break
done