API Docs

v0.4.0GitHub

API docs

Use Stackray's shared HTTP API to submit scans, watch progress, fetch results, inspect changes, and query stored history from scripts, services, and agents.

Base path

/api/v1

Primary auth

Bearer API key

Streaming

SSE events

Quick start

Start here if you just created an API key and want to verify that your integration works.

1. Create an API key in /settings/api-keys.
2. Set your base URL and API key in your shell or runtime environment.
3. Submit a scan, wait for completion, then fetch GET /scans/:scanId/report.

export STACKRAY_BASE_URL="https://stackray.app"
export STACKRAY_API_KEY="sr_live_your_api_key_here"

curl -X POST "$STACKRAY_BASE_URL/api/v1/scans"   -H "Authorization: Bearer $STACKRAY_API_KEY"   -H "Content-Type: application/json"   -d '{"target":"https://example.com","options":{"followRedirects":true,"includeRawResponse":false},"client":{"source":"api"}}'

curl "$STACKRAY_BASE_URL/api/v1/scans/scn_01J.../report"   -H "Authorization: Bearer $STACKRAY_API_KEY"

Concepts

Most agents can start with the scan report and only use result or target endpoints when they need deeper evidence.

scanId

The scan job you submitted, such as one request to analyze example.com.

resultId

One observed URL/result row inside a scan. Use result-level endpoints only when you already need to inspect a specific row.

comparisonId

One persisted comparison between a completed scan and its selected baseline. Use it to retrieve the full before-and-after evidence behind a change-feed entry.

target

The historical identity Stackray uses to connect repeated scans of the same normalized site over time.

report

The default agent-readable answer for a scan: authoritative result, primary technologies, infrastructure summary, and links to larger paginated collections.

Authentication modes

Product-resource endpoints accept either bearer API keys or browser sessions. Account, admin, and API key management endpoints remain browser-session-only.

Bearer API key

Use this for scans, runs, targets, changes, comparisons, schedules, results, and scan-event streaming.

Authorization: Bearer sr_live_your_api_key_here

Browser session

Use this for the web UI, API key management, user administration, password changes, and product-state endpoints.

/api/v1/api-keys

Use the web app at /settings/api-keys or pass your session cookie.

Submit a scan

POST /scans

Queue a new scan and get a scan ID back immediately.

curl

curl -X POST "$STACKRAY_BASE_URL/api/v1/scans"   -H "Authorization: Bearer $STACKRAY_API_KEY"   -H "Content-Type: application/json"   -d '{
    "target": "https://example.com",
    "options": {
      "followRedirects": true,
      "includeRawResponse": false
    },
    "client": { "source": "api" }
  }'

Response

{
  "scanId": "scn_01J...",
  "status": "queued",
  "reused": false
}

• Each scan represents one target domain or URL.
• Returns scanId, status, and reused immediately.
• Use idempotencyKey when you want replay protection for automation.

Watch progress

GET /scans/:scanId/events

Stream live scan updates with Server-Sent Events or fall back to polling.

curl

curl -N "$STACKRAY_BASE_URL/api/v1/scans/scn_01J.../events" -H "Authorization: Bearer $STACKRAY_API_KEY"

Event stream response

event: scan.status
data: {"scanId":"scn_01J...","status":"running","attemptId":"att_01J...","at":"2026-03-23T12:00:00Z"}

event: scan.progress
data: {"scanId":"scn_01J...","resultCount":1,"subdomainCount":42,"at":"2026-03-23T12:00:02Z"}

event: scan.result
data: {"scanId":"scn_01J...","resultId":"res_01J...","target":"https://example.com","statusCode":200,"finalUrl":"https://example.com","title":"Example Site","server":"nginx","cdn":{"enabled":true,"name":"cloudflare","type":"cdn"},"technologies":["WordPress","PHP"],"at":"2026-03-23T12:00:03Z"}

event: scan.complete
data: {"scanId":"scn_01J...","status":"completed","resultCount":1,"at":"2026-03-23T12:00:04Z"}

• Native browser EventSource does not let you send an Authorization header.
• For browser apps, use a proxy or poll GET /scans/:scanId and GET /scans/:scanId/results instead.
• scan.status attemptId is null when recovery requeues a scan before an attempt exists.
• Event types include scan.status, scan.progress, scan.result, scan.complete, scan.failed, and scan.cancelled.

Poll scan status

GET /scans/:scanId

Fetch the current scan state, attempts, phase progress, result count, and subdomain-discovery summary. Use this when Server-Sent Events are not practical.

curl

curl "$STACKRAY_BASE_URL/api/v1/scans/scn_01J..." -H "Authorization: Bearer $STACKRAY_API_KEY"

Response

{
  "scanId": "scn_01J...",
  "status": "completed",
  "source": "api",
  "target": {
    "inputTarget": "https://example.com",
    "normalizedTarget": "example.com",
    "canonicalTargetId": "ctg_01J..."
  },
  "currentAttempt": {
    "attemptId": "att_01J...",
    "attemptNumber": 1,
    "status": "completed",
    "requestProfile": "baseline",
    "fallbackReason": null,
    "resultCount": 1,
    "forbiddenResultCount": 0
  },
  "attemptHistory": [
    {
      "attemptId": "att_01J...",
      "attemptNumber": 1,
      "status": "completed",
      "requestProfile": "baseline",
      "fallbackReason": null,
      "resultCount": 1,
      "forbiddenResultCount": 0
    }
  ],
  "phases": [],
  "progress": {
    "resultCount": 1,
    "subdomainCount": 42
  },
  "subdomains": {
    "state": "completed",
    "runId": "sdr_01J...",
    "targetDomain": "example.com",
    "resultCount": 42,
    "engineVersion": "subfinder-2.9.0",
    "errorMessage": null,
    "startedAt": "2026-03-23T12:00:02Z",
    "completedAt": "2026-03-23T12:00:07Z"
  }
}

• Poll until status is completed, failed, or cancelled.
• The attempts and phases fields explain retry, headless, browser-recovery, and enrichment progress without returning the full result payload.
• Fetch GET /scans/:scanId/report after completion for the bounded, agent-readable result.

Get the scan summary

GET /scans/:scanId/report

Use this as the default result endpoint for agents. It returns Stackray's authoritative result, primary technologies, infrastructure summary, bounded subdomain sample, and links to paginated evidence.

curl

curl "$STACKRAY_BASE_URL/api/v1/scans/scn_01J.../report" -H "Authorization: Bearer $STACKRAY_API_KEY"

Response

{
  "scan": {
    "scanId": "scn_01J...",
    "status": "completed",
    "source": "api",
    "target": {
      "inputTarget": "https://example.com",
      "normalizedTarget": "example.com",
      "canonicalTargetId": "ctg_01J..."
    },
    "currentAttempt": {
      "attemptId": "att_01J...",
      "attemptNumber": 1,
      "status": "completed",
      "requestProfile": "baseline",
      "fallbackReason": null,
      "resultCount": 1,
      "forbiddenResultCount": 0
    },
    "attemptHistory": [
      {
        "attemptId": "att_01J...",
        "attemptNumber": 1,
        "status": "completed",
        "requestProfile": "baseline",
        "fallbackReason": null,
        "resultCount": 1,
        "forbiddenResultCount": 0
      }
    ],
    "phases": [],
    "progress": {
      "resultCount": 1,
      "subdomainCount": 500
    },
    "subdomains": {
      "state": "completed",
      "runId": "sdr_01J...",
      "targetDomain": "example.com",
      "resultCount": 500,
      "engineVersion": "subfinder-2.9.0",
      "errorMessage": null,
      "startedAt": "2026-03-23T12:00:02Z",
      "completedAt": "2026-03-23T12:00:07Z"
    },
    "submittedAt": "2026-03-23T12:00:00Z",
    "completedAt": "2026-03-23T12:00:12Z"
  },
  "authoritativeResult": {
    "resultId": "res_01J...",
    "url": "https://example.com",
    "finalUrl": "https://example.com",
    "title": "Example Site",
    "statusCode": 200,
    "server": "nginx",
    "cdn": {
      "enabled": true,
      "name": "cloudflare",
      "type": "cdn"
    },
    "screenshotUrl": "/api/v1/scans/scn_01J.../results/res_01J.../screenshot",
    "faviconUrl": "/api/v1/scans/scn_01J.../results/res_01J.../favicon"
  },
  "technologies": {
    "scope": "authoritative",
    "total": 2,
    "items": [
      {
        "scanId": "scn_01J...",
        "resultId": "res_01J...",
        "canonicalTargetId": "ctg_01J...",
        "url": "https://example.com",
        "kind": "technology",
        "sources": ["wappalyzer"],
        "displayName": "Next.js",
        "normalizedName": "nextjs",
        "version": null,
        "description": "Next.js is a React framework...",
        "website": "https://nextjs.org",
        "iconUrl": null,
        "categories": ["Web frameworks"],
        "primaryCategory": "Web frameworks",
        "bucket": "framework",
        "inferred": false,
        "vendor": null,
        "product": null,
        "cpe": null
      }
    ]
  },
  "infrastructure": {
    "dns": {
      "hostIp": "203.0.113.10",
      "a": ["203.0.113.10"],
      "aaaa": [],
      "cname": [],
      "resolvers": ["1.1.1.1:53"]
    },
    "asn": {
      "asNumber": "13335",
      "org": "Cloudflare, Inc."
    },
    "tls": null,
    "capabilities": null,
    "ipIntelligence": null
  },
  "subdomains": {
    "summary": {
      "state": "completed",
      "runId": "sdr_01J...",
      "targetDomain": "example.com",
      "resultCount": 500,
      "engineVersion": "subfinder-2.9.0",
      "errorMessage": null,
      "startedAt": "2026-03-23T12:00:02Z",
      "completedAt": "2026-03-23T12:00:07Z"
    },
    "sample": [
      {
        "subdomainId": "sub_01J...",
        "scanId": "scn_01J...",
        "host": "app.example.com",
        "rootDomain": "example.com",
        "ip": "203.0.113.11",
        "source": "subfinder",
        "wildcardCertificate": false,
        "observedAt": "2026-03-23T12:00:05Z",
        "rawSubfinder": {}
      }
    ],
    "total": 500,
    "truncated": true,
    "next": "/api/v1/scans/scn_01J.../subdomains?page=2&pageSize=50"
  },
  "links": {
    "scan": "/api/v1/scans/scn_01J...",
    "results": "/api/v1/scans/scn_01J.../results",
    "technologies": "/api/v1/scans/scn_01J.../technologies?scope=authoritative",
    "subdomains": "/api/v1/scans/scn_01J.../subdomains",
    "events": "/api/v1/scans/scn_01J.../events"
  }
}

• Use this as the default endpoint for agent-readable scan detail.
• The report is bounded: large collections such as subdomains are summarized with a sample and links to paginated endpoints.
• Technologies use the authoritative result selected by Stackray, so agents do not need to choose a resultId for common questions.

Get changes for a scan

GET /scans/:scanId/comparison

Retrieve the completed scan's comparison against its selected baseline, along with recent baseline choices. This is the easiest way for automation to ask what changed after a scan finishes.

curl

curl "$STACKRAY_BASE_URL/api/v1/scans/scn_01J_current/comparison" -H "Authorization: Bearer $STACKRAY_API_KEY"

Response

{
  "comparison": {
    "id": "cmp_01J...",
    "canonicalTargetId": "ctg_01J...",
    "status": "completed",
    "algorithmVersion": 20,
    "currentScan": {
      "id": "scn_01J_current",
      "target": "https://example.com",
      "completedAt": "2026-03-24T12:00:12Z",
      "faviconUrl": null
    },
    "baselineScan": {
      "id": "scn_01J_baseline",
      "target": "https://example.com",
      "completedAt": "2026-03-23T12:00:12Z"
    },
    "baselineMode": "previous",
    "counts": {
      "total": 1,
      "alertEligible": 1
    },
    "items": [
      {
        "id": "chg_01J...",
        "category": "technology",
        "changeType": "technology.changed",
        "fieldPath": "technologies",
        "summary": "Detected technologies changed",
        "endpointIdentity": "https://example.com/",
        "before": ["React"],
        "after": ["Next.js", "React"],
        "alertEligible": true
      }
    ],
    "errorMessage": null,
    "createdAt": "2026-03-24T12:00:13Z"
  },
  "baselineOptions": [
    {
      "id": "scn_01J_baseline",
      "target": "https://example.com",
      "completedAt": "2026-03-23T12:00:12Z",
      "selected": true,
      "pinned": false
    }
  ],
  "state": "ready",
  "canManageBaseline": true
}

• state is baseline_established when this is the target's first completed scan, pending while comparison work is queued, ready when evidence is available, and failed when comparison failed.
• Pass baselineScanId as a query parameter to inspect an ad hoc comparison against another available scan for the same target.
• alertEligible identifies meaningful changes that can match alert policies. It does not guarantee delivery because policy filters, channels, and cooldowns still apply.

Get primary technologies

GET /scans/:scanId/technologies

Use this to answer technology questions about the authoritative scan result, including metadata for a specific technology such as Next.js.

curl

curl "$STACKRAY_BASE_URL/api/v1/scans/scn_01J.../technologies?scope=authoritative&q=Next.js"   -H "Authorization: Bearer $STACKRAY_API_KEY"

Response

{
  "items": [
    {
      "scanId": "scn_01J...",
      "resultId": "res_01J...",
      "canonicalTargetId": "ctg_01J...",
      "url": "https://example.com",
      "kind": "technology",
      "sources": ["wappalyzer", "cpe"],
      "displayName": "Next.js",
      "normalizedName": "nextjs",
      "version": null,
      "description": "Next.js is a React framework...",
      "website": "https://nextjs.org",
      "iconUrl": null,
      "categories": ["Web frameworks", "JavaScript frameworks"],
      "primaryCategory": "Web frameworks",
      "bucket": "framework",
      "inferred": false,
      "vendor": null,
      "product": null,
      "cpe": null
    }
  ],
  "page": 1,
  "pageSize": 1,
  "total": 1
}

• Use scope=authoritative for the selected primary result; this response is not paginated.
• Use scope=all-results for the paginated aggregate over matching result rows.
• Use q, source, and bucket to narrow metadata questions without paging raw result rows.

Page through observed result rows

GET /scans/:scanId/results

Use this when the bounded scan summary is not enough and you need the lower-level URLs/results observed during the scan.

curl

curl "$STACKRAY_BASE_URL/api/v1/scans/scn_01J.../results?page=1&pageSize=20"   -H "Authorization: Bearer $STACKRAY_API_KEY"

Response

{
  "items": [
    {
      "resultId": "res_01J...",
      "target": "https://example.com",
      "input": "https://example.com",
      "url": "https://example.com",
      "finalUrl": "https://example.com",
      "path": "/",
      "method": "GET",
      "title": "Example Site",
      "statusCode": 200,
      "server": "nginx/1.24.0",
      "contentType": "text/html; charset=UTF-8",
      "contentLength": 12345,
      "responseTimeMs": 187,
      "cdn": { "enabled": true, "name": "cloudflare", "type": "cdn" },
      "dns": {
        "hostIp": "104.21.0.1",
        "a": ["104.21.0.1"],
        "aaaa": [],
        "cname": [],
        "resolvers": ["1.1.1.1:53"]
      },
      "asn": { "asNumber": "13335", "org": "Cloudflare, Inc." },
      "technologies": ["WordPress", "PHP"],
      "wordpress": { "plugins": ["jetpack"], "themes": [] },
      "cpe": [],
      "favicon": { "mmh3": "1494302000", "md5": "...", "url": null, "path": null },
      "hashes": { "md5": "...", "mmh3": "...", "sha256": "...", "simhash": "..." },
      "capabilities": { "http2": true, "pipeline": false, "websocket": false, "vhost": false },
      "redirectChain": { "statusCodes": [301, 200], "items": [] },
      "bodyPreview": "...",
      "bodyDomains": [],
      "bodyFqdns": [],
      "rawHttpx": {}
    }
  ],
  "page": 1,
  "pageSize": 20,
  "total": 1
}

• A scan is single-target, but it can still emit multiple persisted result rows across attempts or profiles.
• Supported query params include page, pageSize, target, technology, statusCode, and includeIncomplete.
• The response keeps normalized fields first and can include rawHttpx for full evidence.
• Use the dedicated technology endpoints when you want flat technology inventory rows without the rest of the scan result fields.

Page through subdomains

GET /scans/:scanId/subdomains

Use this when a report says the subdomain list is truncated and you need the full paginated collection.

curl

curl "$STACKRAY_BASE_URL/api/v1/scans/scn_01J.../subdomains?page=1&pageSize=50"   -H "Authorization: Bearer $STACKRAY_API_KEY"

Response

{
  "summary": {
    "state": "completed",
    "runId": "sdr_01J...",
    "targetDomain": "example.com",
    "resultCount": 42,
    "engineVersion": null,
    "errorMessage": null,
    "startedAt": "2026-03-23T12:00:02Z",
    "completedAt": "2026-03-23T12:00:07Z"
  },
  "items": [
    {
      "subdomainId": "sub_01J...",
      "scanId": "scn_01J...",
      "host": "shop.example.com",
      "rootDomain": "example.com",
      "ip": "203.0.113.10",
      "source": "crtsh",
      "wildcardCertificate": false,
      "observedAt": "2026-03-23T12:00:05Z",
      "rawSubfinder": {}
    }
  ],
  "page": 1,
  "pageSize": 50,
  "total": 42
}

• Subdomain rows are DNS-validated by Subfinder's active mode, not HTTP-live probes.
• pageSize is capped at 250.
• The compact subdomain summary is also available on GET /scans/:scanId.
• Use GET /scans/:scanId/results for httpx result rows and content-derived body domains.

Advanced: technologies for one result row

GET /scans/:scanId/results/:resultId/technologies

Use this only when you already know the exact resultId and need technology rows for that specific observed URL/result.

curl

curl "$STACKRAY_BASE_URL/api/v1/scans/scn_01J.../results/res_01J.../technologies"   -H "Authorization: Bearer $STACKRAY_API_KEY"

Response

{
  "items": [
    {
      "scanId": "scn_01J...",
      "resultId": "res_01J...",
      "canonicalTargetId": "ctg_01J...",
      "url": "https://example.com",
      "kind": "technology",
      "sources": ["wappalyzer", "cpe"],
      "displayName": "WordPress",
      "normalizedName": "wordpress",
      "version": null,
      "description": "Blog tool and publishing platform.",
      "website": "https://wordpress.org",
      "iconUrl": null,
      "categories": ["CMS"],
      "primaryCategory": "CMS",
      "bucket": "platform",
      "inferred": false,
      "vendor": null,
      "product": null,
      "cpe": null
    },
    {
      "scanId": "scn_01J...",
      "resultId": "res_01J...",
      "canonicalTargetId": "ctg_01J...",
      "url": "https://example.com",
      "kind": "wordpress_plugin",
      "sources": ["wordpress"],
      "displayName": "Jetpack",
      "normalizedName": "jetpack",
      "version": null,
      "description": null,
      "website": null,
      "iconUrl": null,
      "categories": [],
      "primaryCategory": null,
      "bucket": "ecosystem",
      "inferred": false,
      "vendor": null,
      "product": null,
      "cpe": null
    }
  ],
  "total": 2
}

• Use this when you already know the exact resultId you want.
• The route returns a flat list of detection rows for the exact result row you selected, not the scan-level aggregate.

Search scan history

GET /runs

Find previous scans by status, source, target text, or sort order. Use this to locate a scanId before fetching a report.

curl

curl "$STACKRAY_BASE_URL/api/v1/runs?status=completed&limit=20" -H "Authorization: Bearer $STACKRAY_API_KEY"

Response

{
  "items": [
    {
      "scanId": "scn_01J...",
      "status": "completed",
      "source": "cli",
      "target": "https://example.com",
      "submittedAt": "2026-03-23T12:00:00Z",
      "completedAt": "2026-03-23T12:00:12Z"
    }
  ],
  "nextCursor": null
}

• Supported query params include q, status, source, sort, cursor, and limit.
• Use q to search scan IDs and scanned target identity such as URLs, hostnames, and domains.

List detected changes

GET /changes

Page through recent scan comparisons across visible targets. Feed entries include compact previews and separate counts for all stored changes and alert-eligible changes.

curl

curl "$STACKRAY_BASE_URL/api/v1/changes?target=example.com&category=technology&limit=20"   -H "Authorization: Bearer $STACKRAY_API_KEY"

Response

{
  "items": [
    {
      "id": "cmp_01J...",
      "canonicalTargetId": "ctg_01J...",
      "status": "completed",
      "algorithmVersion": 20,
      "currentScan": {
        "id": "scn_01J_current",
        "target": "https://example.com",
        "completedAt": "2026-03-24T12:00:12Z",
        "faviconUrl": null
      },
      "baselineScan": {
        "id": "scn_01J_baseline",
        "target": "https://example.com",
        "completedAt": "2026-03-23T12:00:12Z"
      },
      "baselineMode": "previous",
      "counts": {
        "total": 3,
        "alertEligible": 1,
        "matching": 1
      },
      "items": [
        {
          "id": "chg_01J...",
          "category": "technology",
          "changeType": "technology.changed",
          "summary": "Detected technologies changed",
          "preview": "Next.js added"
        }
      ],
      "itemsTruncated": false,
      "errorMessage": null,
      "createdAt": "2026-03-24T12:00:13Z"
    }
  ],
  "nextCursor": null
}

• Supported query params are cursor, limit (maximum 100), target, and category.
• category accepts availability, content, infrastructure, tls, technology, discovery, or security.
• counts.total includes routine stored changes; counts.alertEligible is the subset that can match alert policies; counts.matching reflects the active feed filters.
• Feed items are compact. Fetch GET /changes/:comparisonId for complete field paths and before-and-after evidence.

Advanced: get a full comparison

GET /changes/:comparisonId

Fetch every retained change item and its bounded before-and-after evidence for one comparison selected from the change feed.

curl

curl "$STACKRAY_BASE_URL/api/v1/changes/cmp_01J..." -H "Authorization: Bearer $STACKRAY_API_KEY"

Response

{
  "id": "cmp_01J...",
  "canonicalTargetId": "ctg_01J...",
  "status": "completed",
  "algorithmVersion": 20,
  "currentScan": {
    "id": "scn_01J_current",
    "target": "https://example.com",
    "completedAt": "2026-03-24T12:00:12Z",
    "faviconUrl": null
  },
  "baselineScan": {
    "id": "scn_01J_baseline",
    "target": "https://example.com",
    "completedAt": "2026-03-23T12:00:12Z"
  },
  "baselineMode": "previous",
  "counts": {
    "total": 1,
    "alertEligible": 1
  },
  "items": [
    {
      "id": "chg_01J...",
      "category": "technology",
      "changeType": "technology.changed",
      "fieldPath": "technologies",
      "summary": "Detected technologies changed",
      "endpointIdentity": "https://example.com/",
      "before": ["React"],
      "after": ["Next.js", "React"],
      "alertEligible": true
    }
  ],
  "errorMessage": null,
  "createdAt": "2026-03-24T12:00:13Z"
}

• Use the comparison ID returned by GET /changes or GET /scans/:scanId/comparison.
• before and after are bounded JSON evidence, so their shape varies with changeType.
• A 404 comparison_not_found response means the comparison does not exist or is not visible to the caller.

Search historical targets

GET /targets/results

Search the latest successful snapshot for each canonical target when you care about site history rather than one scan job.

curl

curl "$STACKRAY_BASE_URL/api/v1/targets/results?q=example.com&technology=php"   -H "Authorization: Bearer $STACKRAY_API_KEY"

Response

{
  "items": [
    {
      "canonicalTargetId": "ctg_01J...",
      "normalizedTarget": "https://example.com",
      "latestScanId": "scn_01J...",
      "title": "Example Site",
      "technologies": ["WordPress", "PHP"],
      "lastScannedAt": "2026-03-23T12:00:12Z",
      "faviconUrl": "https://example.com/favicon.ico"
    }
  ],
  "nextCursor": null
}

• Supported filters include q, technology, cdn, server, plugin, theme, cpe, statusCode, from, to, cursor, and limit.
• Use q to search scanned target identity such as URLs, hostnames, and domains; use structured filters for technology and evidence lookup.
• Use GET /targets/:canonicalTargetId/history to inspect the scan history for a specific canonical target.
• Use GET /targets/:canonicalTargetId/technologies to retrieve flat technology inventory rows for a target.

Get target scan history

GET /targets/:canonicalTargetId/history

List scans associated with one canonical target. Use this after target search to walk a site's history without repeating a text query.

curl

curl "$STACKRAY_BASE_URL/api/v1/targets/ctg_01J.../history?limit=10" -H "Authorization: Bearer $STACKRAY_API_KEY"

Response

{
  "canonicalTargetId": "ctg_01J...",
  "normalizedTarget": "https://example.com",
  "items": [
    {
      "scanId": "scn_01J_current",
      "status": "completed",
      "title": "Example Site",
      "technologies": ["Next.js", "React"],
      "submittedAt": "2026-03-24T12:00:00Z",
      "completedAt": "2026-03-24T12:00:12Z"
    },
    {
      "scanId": "scn_01J_baseline",
      "status": "completed",
      "title": "Example Site",
      "technologies": ["React"],
      "submittedAt": "2026-03-23T12:00:00Z",
      "completedAt": "2026-03-23T12:00:12Z"
    }
  ],
  "totalCount": 2,
  "hasMore": false
}

• limit defaults to 10; pass limit=all when you explicitly need the complete visible history.
• Pass excludeScanId to omit one scan, which is useful when selecting a comparison baseline.
• Resolve canonicalTargetId through GET /targets/results or from a scan response.

Advanced: find targets using technologies

GET /targets/technology-comparison

Find the latest target snapshots that contain every requested technology. This is useful for inventory questions such as which sites use both Next.js and Cloudflare.

curl

curl "$STACKRAY_BASE_URL/api/v1/targets/technology-comparison?technology=Next.js&technology=Cloudflare"   -H "Authorization: Bearer $STACKRAY_API_KEY"

Response

{
  "technology": "Next.js",
  "technologies": ["Next.js", "Cloudflare"],
  "items": [
    {
      "canonicalTargetId": "ctg_01J...",
      "normalizedTarget": "https://example.com",
      "latestScanId": "scn_01J...",
      "title": "Example Site",
      "technologies": ["Cloudflare", "Next.js", "React"],
      "matchedTechnology": "Next.js",
      "matchedTechnologyIconUrl": null,
      "matchedTechnologies": [
        {
          "name": "Next.js",
          "iconUrl": null
        },
        {
          "name": "Cloudflare",
          "iconUrl": null
        }
      ],
      "lastScannedAt": "2026-03-24T12:00:12Z",
      "faviconUrl": null,
      "screenshotUrl": null
    }
  ]
}

• Repeat the technology query parameter to require multiple technologies; matching is case-insensitive and every requested value must be present.
• Results use only the latest completed snapshot for each visible canonical target.
• Use GET /targets/results for broader search and infrastructure filters.

Advanced: target technology history

GET /targets/:canonicalTargetId/technologies

Use this after resolving a canonical target when you need technology inventory from the target history view instead of one scan report.

curl

curl "$STACKRAY_BASE_URL/api/v1/targets/ctg_01J.../technologies" -H "Authorization: Bearer $STACKRAY_API_KEY"

Response

{
  "canonicalTargetId": "ctg_01J...",
  "normalizedTarget": "https://example.com",
  "latestScanId": "scn_01J_latest",
  "scanId": "scn_01J...",
  "lastScannedAt": "2026-03-23T12:00:12Z",
  "items": [
    {
      "scanId": "scn_01J...",
      "resultId": "res_01J...",
      "canonicalTargetId": "ctg_01J...",
      "url": "https://example.com",
      "kind": "technology",
      "sources": ["wappalyzer", "cpe"],
      "displayName": "WordPress",
      "normalizedName": "wordpress",
      "version": null,
      "description": "Blog tool and publishing platform.",
      "website": "https://wordpress.org",
      "iconUrl": null,
      "categories": ["CMS"],
      "primaryCategory": "CMS",
      "bucket": "platform",
      "inferred": false,
      "vendor": null,
      "product": null,
      "cpe": null
    },
    {
      "scanId": "scn_01J...",
      "resultId": "res_01J...",
      "canonicalTargetId": "ctg_01J...",
      "url": "https://example.com",
      "kind": "wordpress_plugin",
      "sources": ["wordpress"],
      "displayName": "Jetpack",
      "normalizedName": "jetpack",
      "version": null,
      "description": null,
      "website": null,
      "iconUrl": null,
      "categories": [],
      "primaryCategory": null,
      "bucket": "ecosystem",
      "inferred": false,
      "vendor": null,
      "product": null,
      "cpe": null
    }
  ]
}

• Without scanId, the endpoint returns the latest completed scan for the canonical target that the caller can access.
• With scanId, the endpoint returns the technology payload for that target within the selected scan.

List schedules

GET /schedules

Fetch recurring schedule definitions owned by the caller. A single schedule can group many targets and each dispatch can fan out into many single-target scans.

curl

curl "$STACKRAY_BASE_URL/api/v1/schedules" -H "Authorization: Bearer $STACKRAY_API_KEY"

Response

{
  "items": [
    {
      "scheduleId": "sch_01J...",
      "targets": ["https://example.com/", "https://example2.com/"],
      "frequency": "weekly",
      "timeOfDay": "10:15",
      "weekday": 1,
      "dayOfMonth": null,
      "timezone": "America/New_York",
      "enabled": true,
      "nextRunAt": "2026-04-18T14:15:00.000Z",
      "lastScheduledForAt": "2026-04-11T23:42:42.888Z",
      "lastScanId": "scn_01J...",
      "lastRunStatus": "queued",
      "lastRunLabel": "Queued",
      "createdAt": "2026-04-11T23:43:25.762Z"
    }
  ]
}

• The response is already filtered to schedules the caller can see.
• weekday is only present for weekly schedules; dayOfMonth is only present for monthly schedules.
• lastScanId points at one scan linked to the latest dispatch group so the UI can deep-link into recent activity.

Create a schedule

POST /schedules

Store a recurring schedule definition that can target many domains and fan out into one scan per target each time it fires.

curl

curl -X POST "$STACKRAY_BASE_URL/api/v1/schedules"   -H "Authorization: Bearer $STACKRAY_API_KEY"   -H "Content-Type: application/json"   -d '{
    "targets": ["https://example.com", "https://example2.com"],
    "frequency": "weekly",
    "timeOfDay": "10:15",
    "weekday": 1,
    "timezone": "America/New_York",
    "options": {
      "followRedirects": true
    }
  }'

Response

{
  "scheduleId": "sch_01J..."
}

• Use frequency=daily, weekly, or monthly.
• weekly schedules require weekday (0=Sun through 6=Sat); monthly schedules require dayOfMonth (1-31).
• timezone must be a valid IANA timezone string such as America/New_York.
• When the schedule fires, the backend creates one scan per target instead of creating a multi-target scan.

Pause or resume a schedule

PATCH /schedules/:scheduleId

Toggle whether a stored schedule is eligible for future dispatch.

curl

curl -X PATCH "$STACKRAY_BASE_URL/api/v1/schedules/sch_01J..."   -H "Authorization: Bearer $STACKRAY_API_KEY"   -H "Content-Type: application/json"   -d '{
    "enabled": false
  }'

Response

{
  "scheduleId": "sch_01J...",
  "enabled": false
}

• Set enabled=false to pause dispatching without deleting the schedule.
• Set enabled=true to resume future dispatching.

Delete a schedule

DELETE /schedules/:scheduleId

Permanently remove a schedule definition and stop future dispatches for it.

curl

curl -X DELETE "$STACKRAY_BASE_URL/api/v1/schedules/sch_01J..." -H "Authorization: Bearer $STACKRAY_API_KEY"

Response

{
  "deletedScheduleId": "sch_01J..."
}

• Deletion removes the stored recurring schedule definition.
• Historical scans created by that schedule remain part of normal run history.

API key management

API key management is part of the same API surface, but it is intentionally session-authenticated rather than bearer-authenticated.

GET /api-keys

List the API keys owned by the signed-in user.

Response

{
  "items": [
    {
      "id": "0f5d7a0c-8eb9-4d92-9f61-76e2f5a29b10",
      "name": "Automation script",
      "keyHint": "sr_live_abcd12",
      "lastUsedAt": "2026-03-23T12:00:00Z",
      "createdAt": "2026-03-20T10:00:00Z"
    }
  ]
}

POST /api-keys

Create a new API key and reveal the full value once.

Response

{
  "apiKey": {
    "id": "0f5d7a0c-8eb9-4d92-9f61-76e2f5a29b10",
    "name": "Automation script",
    "keyHint": "sr_live_abcd12",
    "lastUsedAt": null,
    "createdAt": "2026-03-23T12:00:00Z"
  },
  "plainTextApiKey": "sr_live_secret_abc123xyz..."
}

DELETE /api-keys/:apiKeyId

Revoke an existing API key so it can no longer authenticate new requests.

Response

{
  "revokedApiKeyId": "0f5d7a0c-8eb9-4d92-9f61-76e2f5a29b10"
}

Use /settings/api-keys in the authenticated web app for API key management.

If you call these routes outside the browser, send your session cookie.
API keys cannot create, list, or revoke API keys.

Error handling

{
  "error": {
    "code": "invalid_target",
    "message": "One or more targets could not be normalized.",
    "details": {}
  }
 }

invalid_api_key: API key invalid, deleted, or no longer active

invalid_authorization_header: malformed Authorization header

invalid_target: target URL could not be processed

scan_not_found: requested scan does not exist or is not visible

comparison_not_found: requested comparison does not exist or is not visible

comparison_read_failed: comparison could not be loaded or generated

changes_list_failed: change feed could not be loaded

forbidden: insufficient permissions

unauthenticated: no valid auth provided

API key access is disabled for this account

You can still review the API shape here, but you will need an admin to re-enable API key access before you can authenticate with an API key.