APIs

Trigger crawls, pull findings, and manage projects over HTTP — for CI pipelines, monitoring scripts, and custom dashboards.

The Digispot HTTP API lets you trigger crawls and pull results from your own scripts, pipelines, or dashboards. It is available on the Cloud Platform.

Generate an API key under Settings → API Keys in the Cloud Platform. Keys are prefixed dsp_live_ for production and dsp_test_ for sandbox.

Authentication

Pass your key as a bearer token on every request:

curl https://api.digispot.ai/v1/projects \
  -H "Authorization: Bearer $DIGISPOT_API_KEY"

All endpoints return JSON. Errors use standard HTTP status codes with a message field in the response body.

Projects

List projects

curl https://api.digispot.ai/v1/projects \
  -H "Authorization: Bearer $DIGISPOT_API_KEY"

Response includes id, name, url, lastCrawledAt, and plan.

Get a project

curl https://api.digispot.ai/v1/projects/prj_123 \
  -H "Authorization: Bearer $DIGISPOT_API_KEY"

Crawls

Start a crawl

curl -X POST https://api.digispot.ai/v1/crawls \
  -H "Authorization: Bearer $DIGISPOT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "projectId": "prj_123",
    "url": "https://example.com",
    "options": {
      "maxPages": 500,
      "renderJs": true,
      "device": "mobile"
    }
  }'

Returns { "crawlId": "crawl_abc", "status": "queued" }.

Get crawl status

curl https://api.digispot.ai/v1/crawls/crawl_abc \
  -H "Authorization: Bearer $DIGISPOT_API_KEY"

status is one of queued, running, completed, or failed. A completed crawl includes pagesFound, issueCount, and scores.

List crawls for a project

curl "https://api.digispot.ai/v1/crawls?projectId=prj_123&limit=10" \
  -H "Authorization: Bearer $DIGISPOT_API_KEY"

Issues

List issues for a crawl

curl "https://api.digispot.ai/v1/issues?crawlId=crawl_abc&severity=error" \
  -H "Authorization: Bearer $DIGISPOT_API_KEY"

Filterable by severity (error, warning, info), category (e.g. links, schema, performance), and page (a specific URL).

Each issue includes:

check — the check name (e.g. missing-meta-description)
severity — error, warning, or info
affectedUrls — list of pages with this issue
description — what the check tests
recommendation — the specific fix

Pages

Get a page report

curl "https://api.digispot.ai/v1/pages?crawlId=crawl_abc&url=https://example.com/blog" \
  -H "Authorization: Bearer $DIGISPOT_API_KEY"

Returns all check results, scores, and metadata for that URL.

CI integration example

A typical CI workflow triggers a crawl after deployment, polls until complete, then fails the build if the error count exceeds a threshold:

#!/bin/bash
# Start crawl
CRAWL_ID=$(curl -s -X POST https://api.digispot.ai/v1/crawls \
  -H "Authorization: Bearer $DIGISPOT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"projectId": "prj_123", "url": "https://example.com"}' \
  | jq -r '.crawlId')

# Poll until complete
while true; do
  STATUS=$(curl -s https://api.digispot.ai/v1/crawls/$CRAWL_ID \
    -H "Authorization: Bearer $DIGISPOT_API_KEY" | jq -r '.status')
  [ "$STATUS" = "completed" ] && break
  [ "$STATUS" = "failed" ] && echo "Crawl failed" && exit 1
  sleep 15
done

# Fail if more than 0 errors
ERRORS=$(curl -s "https://api.digispot.ai/v1/issues?crawlId=$CRAWL_ID&severity=error" \
  -H "Authorization: Bearer $DIGISPOT_API_KEY" | jq '.total')
[ "$ERRORS" -gt 0 ] && echo "Found $ERRORS errors" && exit 1
echo "No errors found"