REST API

# 1. Get your API key from Settings → API in the dashboard.
export WW_KEY="ww_..."        # the full key you copied at creation time
 
# 2. List your modules to find the one you want to scan.
curl https://api.welcomingweb.com/api/public/v1/web/modules \
  -H "Authorization: Bearer $WW_KEY"
 
# 3. Trigger a scan. Save the sessionId.
SESSION_ID=$(curl -s -X POST \
  https://api.welcomingweb.com/api/public/v1/web/modules/123/scan \
  -H "Authorization: Bearer $WW_KEY" \
  | jq -r .sessionId)
 
# 4. Poll until done.
while true; do
  STATUS=$(curl -s \
    https://api.welcomingweb.com/api/public/v1/web/modules/123/sessions/$SESSION_ID \
    -H "Authorization: Bearer $WW_KEY" \
    | jq -r .status)
  echo "Scan status: $STATUS"
  case "$STATUS" in
    SUCCESS) break ;;
    FAILED)  echo "Scan failed"; exit 1 ;;
    *)       sleep 15 ;;
  esac
done

[
  {
    "id": 123,
    "domain": "example.com",
    "plan": "PRO",
    "status": "ACTIVE"
  },
  {
    "id": 124,
    "domain": "other-site.com",
    "plan": "FREE",
    "status": "INACTIVE"
  }
]

{
  "status": "queued",
  "sessionId": 1573,
  "moduleId": 123,
  "used": 3,
  "limit": 5,
  "remaining": 2,
  "resetsAt": "2026-06-01T00:00:00+01:00",
  "message": "Scan started. 2 manual scans remaining this month."
}

{
  "sessionId": 1573,
  "moduleId": 123,
  "status": "EXECUTING",
  "startedAt": "2026-05-20T14:32:11",
  "completedAt": null,
  "message": null,
  "pagesDiscovered": 0,
  "pagesAnalyzed": 0,
  "uniqueIssues": 0,
  "totalOccurrences": 0,
  "p1Count": 0,
  "p2Count": 0,
  "p3Count": 0,
  "p4Count": 0,
  "wcagBand": null,
  "qualityScore": 0.0
}

{
  "sessionId": 1573,
  "moduleId": 123,
  "status": "SUCCESS",
  "startedAt": "2026-05-20T14:32:11",
  "completedAt": "2026-05-20T14:36:42",
  "message": null,
  "pagesDiscovered": 47,
  "pagesAnalyzed": 47,
  "uniqueIssues": 521,
  "totalOccurrences": 4264,
  "p1Count": 0,
  "p2Count": 268,
  "p3Count": 583,
  "p4Count": 29,
  "wcagBand": "Fails A",
  "qualityScore": 79.5
}

name: Accessibility scan
on:
  push:
    branches: [main]
 
jobs:
  scan:
    runs-on: ubuntu-latest
    steps:
      - name: Trigger scan and wait
        env:
          WW_KEY: ${{ secrets.WELCOMINGWEB_API_KEY }}
          MODULE_ID: 123
          MIN_QUALITY: 70
        run: |
          set -euo pipefail
          API=https://api.welcomingweb.com/api/public/v1/web
 
          SESSION_ID=$(curl -s -X POST \
            "$API/modules/$MODULE_ID/scan" \
            -H "Authorization: Bearer $WW_KEY" \
            | jq -r .sessionId)
 
          echo "Started session $SESSION_ID"
 
          for i in {1..60}; do
            RESP=$(curl -s "$API/modules/$MODULE_ID/sessions/$SESSION_ID" \
              -H "Authorization: Bearer $WW_KEY")
            STATUS=$(echo "$RESP" | jq -r .status)
            echo "Attempt $i: $STATUS"
            case "$STATUS" in
              SUCCESS)
                SCORE=$(echo "$RESP" | jq -r .qualityScore)
                P1=$(echo "$RESP" | jq -r .p1Count)
                echo "Quality score: $SCORE, P1 issues: $P1"
                if [ "$P1" -gt 0 ]; then
                  echo "::error::Scan found $P1 P1 (critical) issues"
                  exit 1
                fi
                if [ "$(echo "$SCORE < $MIN_QUALITY" | bc)" -eq 1 ]; then
                  echo "::error::Quality score $SCORE below threshold $MIN_QUALITY"
                  exit 1
                fi
                exit 0
                ;;
              FAILED)
                echo "::error::Scan failed"; exit 2 ;;
              *) sleep 15 ;;
            esac
          done
          echo "::error::Timed out after 15 minutes"; exit 3

accessibility:
  stage: test
  script:
    - apt-get update && apt-get install -y curl jq
    - |
      SESSION_ID=$(curl -s -X POST \
        "$WW_API/modules/$MODULE_ID/scan" \
        -H "Authorization: Bearer $WW_KEY" | jq -r .sessionId)
      while true; do
        STATUS=$(curl -s \
          "$WW_API/modules/$MODULE_ID/sessions/$SESSION_ID" \
          -H "Authorization: Bearer $WW_KEY" | jq -r .status)
        [ "$STATUS" = "SUCCESS" ] && exit 0
        [ "$STATUS" = "FAILED"  ] && exit 1
        sleep 15
      done
  variables:
    WW_API: https://api.welcomingweb.com/api/public/v1/web
    MODULE_ID: "123"