API & CI/CD integration
Scan any public URL with a single request and fail your CI pipeline when the accessibility score drops below your threshold.
Authentication
Send your API key as a Bearer token (Authorization: Bearer nh_live_...) or as an x-api-key header. Requests without a valid key return 401.
API access is an Agency-plan feature. Generate your key from your account page.
Endpoint
POST https://normharbor.com/api/v1/scan or GET https://normharbor.com/api/v1/scan?url=...
Send a URL, get back a JSON scan result — score, grade, totals by severity, and the list of detected issues.
Example request (curl)
curl -s -X POST "https://normharbor.com/api/v1/scan" \
-H "Authorization: Bearer nh_live_your_api_key" \
-H "Content-Type: application/json" \
-d '{"url":"https://example.com"}'Example response
{
"url": "https://example.com",
"score": 87,
"grade": "B",
"totals": { "critical": 0, "serious": 1, "moderate": 2, "minor": 3, "elements": 6 },
"issues": [
{ "id": "img-alt", "wcag": "1.1.1", "level": "A", "impact": "critical", "count": 2 }
],
"scannedAt": "2026-09-23T10:00:00.000Z"
}Errors
| Code | Meaning |
|---|---|
401 | Missing or invalid API key |
403 | Key valid but account is not on the Agency plan |
400 | Missing or empty url |
422 | The target URL could not be scanned (unreachable, blocked, too large, etc.) |
429 | Rate limit exceeded (60 requests/minute per key) |
503 | Service temporarily busy — retry shortly |
Rate limit: 60 requests per minute per API key.
GitHub Action (CI accessibility gate)
Add an accessibility gate to your pipeline: it scans a URL and fails the build if the score is below min-score.
- uses: normharbor/scan-action@v1
with:
api-key: ${{ secrets.NORMHARBOR_API_KEY }}
url: https://example.com
min-score: "90"See the github-action/ folder in the NormHarbor repo for the full action.yml and setup instructions.