API docs

Every endpoint except /api/health needs an API key in every request: Authorization: Bearer sc_…. There are two kinds. An external app key is issued by a BangBang super admin on External apps and works only from that app's own domains and IP addresses; ask your Matter Solutions contact for one. A personal token is created by a super admin under API access. A key acts as its owner: customers reach only their own runs and sites, admins and super admins reach everything. This page and the OpenAPI document are public, so you can share their links with anyone; they never contain a key.

Base URL: https://bangbang.mattersolutions.co. Requests and responses are JSON unless you download an export. Runs are asynchronous: start one, watch /api/jobs or the event stream, then read results.

Run only some tests

Send tests when starting a run: "all" (the default) or a list of the names above. Only those tests run (faster), are scored and get report tabs; an unknown name is 400 with the valid list. The same field works on POST /v1/runs, schedules and POST /v1/runs/preview. GET /v1/tests returns this list as JSON (public).

curl -s -X POST "https://bangbang.mattersolutions.co/v1/sites/www.example.com/runs" \
  -H "Authorization: Bearer $BANGBANG_KEY" -H "content-type: application/json" \
  -d '{"url":"https://www.example.com/","tests":["performance","seo"],"lighthouse":true}'
# 202 {"id":"<run id>", ...}   all tests: "tests":"all" or leave it out

Get one test type's results and files

GET /v1/runs/{id}/tests lists every type in the run: whether it was selected, its scores and finding counts. GET /v1/runs/{id}/tests/{test} returns that type's scores, findings and the evidence per page, environment and device: performance gives Web Vitals and Lighthouse samples (plus CrUX and load results), security the response headers, cookies and TLS, seo the title, meta tags and headings, accessibility the axe violations, responsive the device screenshots and layout issues, content the screenshots and diff images, runtime the status, redirects, console errors and failed requests. Screenshots and diff images are artifact URLs the same key downloads. To get findings only, add test= to /v1/runs/{id}/findings or /v1/sites/{site}/findings.

curl -s -H "Authorization: Bearer $BANGBANG_KEY" "https://bangbang.mattersolutions.co/v1/runs/<run id>/tests"
curl -s -H "Authorization: Bearer $BANGBANG_KEY" "https://bangbang.mattersolutions.co/v1/runs/<run id>/tests/performance"
curl -s -H "Authorization: Bearer $BANGBANG_KEY" "https://bangbang.mattersolutions.co/v1/sites/www.example.com/findings?test=seo,accessibility&severity=medium"
curl -s -H "Authorization: Bearer $BANGBANG_KEY" "https://bangbang.mattersolutions.co/v1/sites/www.example.com/performance?form_factor=mobile"   # Lighthouse history
curl -s -H "Authorization: Bearer $BANGBANG_KEY" -o shot.png "https://bangbang.mattersolutions.co/v1/runs/<run id>/artifacts/shots/…png"  # a file from the response

# GitHub Actions step: fail the build on new high or critical findings
- name: BangBang audit
  env:
    SC: https://bangbang.mattersolutions.co
    TOKEN: ${{ secrets.BANGBANG_TOKEN }}
  run: |
    id=$(curl -sf -X POST "$SC/api/runs" -H "Authorization: Bearer $TOKEN" -H "content-type: application/json" \
      -d '{"mode":"audit","urls":["https://staging.example.com"],"devices":"quick","maxPages":20}' | jq -r .id)
    until [ "$(curl -sf -H "Authorization: Bearer $TOKEN" "$SC/api/jobs" | jq -r --arg id "$id" '.[]|select(.id==$id)|.status')" != "running" ]; do sleep 10; done
    curl -sf -H "Authorization: Bearer $TOKEN" "$SC/api/runs/$id/export/sarif" -o results.sarif
    new=$(curl -sf -H "Authorization: Bearer $TOKEN" "$SC/api/runs/$id/regression" | jq '[.added[]|select(.severity=="high" or .severity=="critical")]|length')
    echo "new high/critical findings: $new"; [ "$new" = "0" ]
- uses: github/codeql-action/upload-sarif@v3
  with: { sarif_file: results.sarif }