CI/CD REST API

Integrate Kuality into your CI pipeline to gate builds on quality thresholds, report coverage, and track test debt over time.

Authentication

All write endpoints require a Bearer token issued from your Organization settings page. Include it as an HTTP header:

Authorization: Bearer ku_live_xxxxxxxxxxxxxxxxxxxx

Scans

POST /api/v1/scans

Trigger a scan and wait for completion (or return immediately with a scan ID).

Request body

{
  "url": "https://example.com",
  "scan_type": "web",
  "fail_on_high": true,
  "score_threshold": 70
}

Response 201

{
  "id": "rpt_abc123",
  "status": "queued",
  "url": "https://kuality.io/reports/rpt_abc123"
}

Scan types

web a11y ssl headers tech cms api jsaudit cookie brokenlinks webvitals seo formaudit

GET /api/v1/scans/:id

Poll a scan for completion. Returns report details including score and finding counts.

{
  "id": "rpt_abc123",
  "status": "completed",
  "score": 84,
  "high": 0,
  "medium": 2,
  "low": 5,
  "grade": "B",
  "url": "https://example.com",
  "completed_at": "2026-04-17T12:00:00Z"
}

Quality Gates

Gate CI deployments on Kuality scores and finding counts. HTTP 200 means all checks passed; HTTP 422 means one or more gates failed. Active alert rules in your organization are also evaluated automatically.

POST /api/v1/gates/evaluate

Evaluates the latest completed scan scores for the given target and scan types against configured thresholds. Omit scan_types to evaluate all scans, omit target to evaluate all targets.

Request body

{
  "target": "https://example.com",
  "scan_types": ["a11y", "webvitals", "headers"],
  "score_threshold": 70,
  "max_high": 0,
  "max_medium": 5
}

Response 200 — all passed

{
  "status": "pass",
  "passed": true,
  "overall_score": 88.3,
  "summary": { "total_checks": 3, "passed_checks": 3, "failed_checks": 0 },
  "checks": [
    { "scan_type": "a11y", "score": 91.0, "high": 0, "passed": true },
    { "scan_type": "webvitals", "score": 87.5, "high": 0, "passed": true },
    { "scan_type": "headers", "score": 86.4, "high": 0, "passed": true }
  ]
}

Response 422 — gate failed

HTTP 422 — one or more gates failed:
{
  "status": "fail",
  "passed": false,
  "overall_score": 61.2,
  "checks": [
    { "scan_type": "a11y", "score": 58.0, "high": 2, "passed": false,
      "reasons": ["score 58 below threshold 70", "2 high-severity findings (max: 0)"] }
  ]
}

GitHub Actions — gate step

- name: Quality gate
  run: |
    curl -sf -X POST KUALITY_URL/api/v1/gates/evaluate \
      -H "Authorization: Bearer KUALITY_TOKEN" \
      -H "Content-Type: application/json" \
      -d '{"target":"STAGING_URL","score_threshold":70,"max_high":0}'

The -f flag causes curl to exit non-zero on HTTP 422, failing the CI step.

Coverage

POST /api/v1/coverage

Upload test coverage data from your CI run.

{
  "project": "my-app",
  "branch": "main",
  "commit_sha": "abc123",
  "statements_pct": 87.4,
  "branches_pct": 72.1,
  "lines_pct": 88.9,
  "changed_files": ["src/auth.ts", "src/api.ts"]
}

GET /api/v1/coverage

Retrieve the latest coverage summary for your organization.

Mutations & Test Debt

POST /api/v1/mutations

Upload mutation testing results (e.g. from Stryker, mutmut).

{
  "project": "my-app",
  "branch": "main",
  "killed": 142,
  "survived": 18,
  "timeout": 3,
  "score": 88.2
}

POST /api/v1/test-debt

Report test debt metrics (skipped tests, TODO counts, flaky tests).

{
  "project": "my-app",
  "branch": "main",
  "skipped": 4,
  "flaky": 2,
  "todo_count": 11,
  "debt_score": 7.5
}

Public endpoints (no auth)

GET /api/v1/badge?target=example.com&type=web

Returns a shields.io-compatible SVG badge with the current Kuality Score. Embed in your README:

![Kuality Score](https://kuality.io/api/v1/badge?target=example.com&type=web)

GET /api/v1/score-graph?target=example.com

Returns a JSON array of score/date tuples for embedding score history charts.

GitHub Actions example

Gate your PR builds on a minimum Kuality Score. Add this step to your workflow:

- name: Run Kuality scan
  uses: kuality-io/scan-action@v1
  with:
    url: ${{ vars.STAGING_URL }}
    scan_type: web
    score_threshold: 70
    fail_on_high: true
    api_token: ${{ secrets.KUALITY_TOKEN }}

Download the full workflow template: kuality-scan.yml

GitLab CI

Add a Kuality quality gate to your GitLab merge request pipelines. Set KUALITY_API_KEY and STAGING_URL as CI/CD variables (Settings → CI/CD → Variables). Mark the API key as masked.

stages:
  - quality

kuality-scan:
  stage: quality
  image: golang:alpine
  before_script:
    - apk add --no-cache curl tar
    - curl -fsSL https://github.com/kuality-io/cli/releases/latest/download/kuality_latest_linux_amd64.tar.gz | tar xz
    - mv kuality /usr/local/bin/
  script:
    - kuality scan "$STAGING_URL" --type web --fail-on high --format junit > kuality-report.xml
  artifacts:
    when: always
    reports:
      junit: kuality-report.xml

Download the full template: kuality-gitlab-ci.yml

The --format junit flag outputs JUnit XML, which GitLab natively displays in the merge request "Test summary" widget. The --fail-on high flag exits non-zero to block the pipeline if high-severity findings are detected.

Jenkins Pipeline

Add a Kuality quality gate to your Jenkins pipeline. Store your API key as a Jenkins credential (Manage Jenkins → Credentials) with ID kuality-api-key. Set STAGING_URL as a pipeline parameter.

pipeline {
    agent any
    environment {
        KUALITY_API_KEY = credentials('kuality-api-key')
    }
    stages {
        stage('Kuality Scan') {
            steps {
                sh 'curl -fsSL https://github.com/kuality-io/cli/releases/latest/download/kuality_latest_linux_amd64.tar.gz | tar xz'
                sh './kuality scan "$STAGING_URL" --type web --fail-on high --format junit > kuality-report.xml'
            }
            post {
                always { junit 'kuality-report.xml' }
            }
        }
    }
}

Download the full template: Jenkinsfile-kuality

The junit post-build step publishes JUnit XML results natively in Jenkins. Failed scans appear as test failures in the build report.

CircleCI

Add a Kuality quality gate to your CircleCI workflows. Set KUALITY_API_KEY and STAGING_URL as environment variables (Project Settings → Environment Variables).

version: 2.1
jobs:
  kuality-scan:
    docker:
      - image: cimg/base:current
    steps:
      - run:
          name: Install Kuality CLI
          command: |
            curl -fsSL https://github.com/kuality-io/cli/releases/latest/download/kuality_latest_linux_amd64.tar.gz | tar xz
            sudo mv kuality /usr/local/bin/
      - run:
          name: Run Kuality scan
          command: kuality scan "$STAGING_URL" --type web --fail-on high --format junit > kuality-report.xml
      - store_test_results:
          path: kuality-report.xml

Download the full template: kuality-circleci.yml

The store_test_results step makes JUnit XML results available in the CircleCI "Tests" tab. The store_artifacts step preserves the raw report for download.

← Scanners

Pricing & Plans

Transparent Pricing →

Cookie settings