API Reference

Authentication

Create an API key in your workspace or through MCP, then send it as a Bearer token:

Authorization: Bearer dxk_...

Available for Growth and Enterprise plans.

Scan flow

To add a new URL, pass enroll_monitoring: true and BotScope will claim an open monitored URL slot before starting the scan. Enterprise has unlimited URL coverage.

Create scan

API_ORIGIN="https://api.botscope.org"

curl -sS -X POST "$API_ORIGIN/api/v1/scans" \
  -H "Authorization: Bearer dxk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "target_url": "https://example.com",
    "scan_mode": "full",
    "enroll_monitoring": true
  }'

Poll and fetch results

JOB="scan_job_id_from_create_scan"

curl -sS "$API_ORIGIN/api/v1/scans/$JOB" \
  -H "Authorization: Bearer dxk_YOUR_KEY"

curl -sS "$API_ORIGIN/api/v1/scans/$JOB/findings" \
  -H "Authorization: Bearer dxk_YOUR_KEY"

curl -sS "$API_ORIGIN/api/v1/scans/$JOB/report" \
  -H "Authorization: Bearer dxk_YOUR_KEY"

Core endpoints

POST/api/v1/scansStart a scan.

GET/api/v1/scans/:scanJobIdPoll status and path progress.

GET/api/v1/scans/:scanJobId/findingsFetch public-safe ABAAM findings.

GET/api/v1/scans/:scanJobId/reportFetch the assembled public report JSON.

GET/api/v1/sample-reportsDaily public `/sample-reports` tab IDs and labels (no auth).

GET/api/v1/monitoringList monitored URLs.

GET/POST/DELETE/api/v1/webhooksManage outbound customer webhooks.

GET/POST/DELETE/api/v1/api-keysManage standard HTTP API keys.

Webhooks

Webhooks notify your systems when scans finish, fail, or monitoring findings change. Payloads include IDs and summary fields; fetch full report data through the API.

Create webhook

curl -sS -X POST "$API_ORIGIN/api/v1/webhooks" \
  -H "Authorization: Bearer dxk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "Agent workflow",
    "url": "https://example.com/botscope/webhooks",
    "event_types": [
      "scan.completed",
      "scan.failed",
      "monitoring.findings_changed"
    ]
  }'

curl -sS "$API_ORIGIN/api/v1/webhooks" \
  -H "Authorization: Bearer dxk_YOUR_KEY"

API key creation

Browser sessions can create keys through the account UI or API. Agents connected through MCP can also call create_api_key when they need standard HTTP access.

Create API key

curl -sS -X POST "$API_ORIGIN/api/v1/api-keys" \
  -H "Cookie: botscope_session=YOUR_BROWSER_SESSION" \
  -H "Content-Type: application/json" \
  -d '{ "label": "CI automation" }'