REST API

Overview

The StackShield API (v1) gives you programmatic access to all the functionality available in the dashboard. You can manage checks (monitored domains), trigger and inspect scans, review scan test results, manage security issues, and pull dashboard statistics.

The API follows REST conventions, returns JSON responses, and uses standard HTTP status codes. All list endpoints are paginated.

Base URL

All API requests are made to:

https://stackshield.io/api/v1

Plan Availability

API access is available on the Professional and Business plans. Teams on the free trial will receive a 403 response when calling API endpoints.

Authentication

Every request must include your team API key as a Bearer token in the Authorization header:

Bearer Token (standard)

curl -H "Authorization: Bearer your-api-key" \
  https://stackshield.io/api/v1/stats

CI/CD Scan Triggers

CI/CD scan triggers use separate hash-authenticated URLs that don't require an API key. You'll find the ready-to-use URLs on each check's edit page. Example:

curl "https://stackshield.io/go/scan/{check_id}/{hash}/trigger"

The hash is unique to your team and acts as authentication — treat these URLs as secrets.

You can generate an API key for the REST API and MCP from your Team Settings page. The key is shown once at creation time — store it securely.

Team Scoping

Your API key is bound to a specific team. All requests are automatically scoped to that team's data. You cannot access checks, scans, or issues belonging to other teams.

Pagination

All list endpoints return paginated results (20 items per page by default). The response includes pagination metadata:

{
  "data": [ ... ],
  "links": {
    "first": "https://app.stackshield.dev/api/v1/checks?page=1",
    "last": "https://app.stackshield.dev/api/v1/checks?page=3",
    "prev": null,
    "next": "https://app.stackshield.dev/api/v1/checks?page=2"
  },
  "meta": {
    "current_page": 1,
    "from": 1,
    "last_page": 3,
    "per_page": 20,
    "to": 20,
    "total": 52
  }
}

Use the page query parameter to navigate: ?page=2

Error Handling

The API uses standard HTTP status codes. Error responses include a JSON body with an error field:

Code	Meaning
200	Success
201	Resource created
204	Deleted (no body)
401	Missing or invalid API key
403	Forbidden — wrong team or plan limitation
404	Resource not found
422	Validation error (details in errors field)

Example error response:

{
  "error": "This check does not belong to your team."
}

Validation errors return field-level details:

{
  "message": "The domain field is required.",
  "errors": {
    "domain": ["The domain field is required."],
    "schedule_frequency": ["The selected schedule frequency is invalid."]
  }
}

Quick Start

Here's a typical workflow to trigger a security scan and check its results:

1. List your checks

curl -H "Authorization: Bearer $API_KEY" \
  https://stackshield.io/api/v1/checks

2. Trigger a scan

curl -X POST -H "Authorization: Bearer $API_KEY" \
  https://stackshield.io/api/v1/checks/{check_id}/scans

3. Check scan status

curl -H "Authorization: Bearer $API_KEY" \
  https://stackshield.io/api/v1/scans/{scan_id}

4. Review test results

curl -H "Authorization: Bearer $API_KEY" \
  https://stackshield.io/api/v1/scans/{scan_id}/tests

5. Check for issues

curl -H "Authorization: Bearer $API_KEY" \
  "https://stackshield.io/api/v1/issues?status=unresolved&severity=critical"

CI/CD Integration

A common use case is running a security scan as part of your deployment pipeline and failing the build if critical issues are found. CI/CD scan triggers use hash-authenticated URLs — no API key needed.

GitHub Actions example

Find your trigger and status URLs on each check's edit page, then store them as repository secrets.

- name: Trigger StackShield scan
  id: scan
  run: |
    RESPONSE=$(curl -sf "${{ secrets.STACKSHIELD_TRIGGER_URL }}")
    echo "scan_id=$(echo $RESPONSE | jq -r '.scan_id')" >> $GITHUB_OUTPUT

- name: Wait for scan completion
  run: |
    for i in $(seq 1 30); do
      RESULT=$(curl -sf \
        "https://stackshield.io/go/scan/${{ steps.scan.outputs.scan_id }}/${{ secrets.STACKSHIELD_HASH }}/status")
      STATUS=$(echo "$RESULT" | jq -r '.status')
      if [ "$STATUS" = "completed" ]; then
        if [ "$(echo "$RESULT" | jq '.has_critical_issues')" = "true" ]; then
          echo "::error::Critical security issues found!"
          exit 1
        fi
        echo "Pass rate: $(echo "$RESULT" | jq '.pass_rate')%"
        exit 0
      fi
      sleep 10
    done
    echo "Scan timed out" && exit 1

Available Resources

The API exposes the following resource groups:

For detailed request/response schemas on every endpoint, see the API Reference.