Skip to main content

​
POST /v1/scanner/scan

Scan a single domain. Returns in 2–5 seconds for most sites. Scope required: scan   Cost: 1 credit 
curl -X POST https://scanner.getsly.ai/v1/scanner/scan \
  -H "Authorization: Bearer $SCANNER_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "domain": "shopify.com",
    "merchant_name": "Shopify",
    "merchant_category": "saas",
    "country_code": "CA",
    "region": "north_america",
    "skip_if_fresh": true
  }'
Request fields:
FieldTypeNotes
domainstringRequired. Normalized server-side (lowercase, no scheme).
merchant_namestringOptional metadata.
merchant_categoryenumretail, saas, marketplace, restaurant, b2b, travel, fintech, healthcare, media, other.
country_codestringISO 3166-1 alpha-2.
regionenumlatam, north_america, europe, apac, africa, mena.
skip_if_freshbooleanIf true, returns the cached scan when it’s under 7 days old (still costs 0 credits).
Response is a full MerchantScan object. The response includes a request_id field (also echoed in the X-Request-ID response header) — the same id appears as source: "request:<uuid>" on the credit ledger row that paid for the scan, so you can join consume rows back to scan results. See audit trail. The response also includes an X-Credits-Remaining header so you can track your balance without an extra call. The TypeScript SDK reads it automatically — see the SDK reference.

​
Errors

Validation typos and server errors are automatically refunded — see auto-refund on 4xx and 5xx. Common errors:
StatusMeaningBody shape
400Validation error{ error: "Validation error", details: { fieldErrors: { domain: ["Required"] } } }
401Bad / expired key{ error: "unauthorized" }
402Insufficient credits (not debited){ error: "insufficient_credits", balance, required, docs }
429Rate limited (not debited; honors Retry-After){ error: "rate_limit_exceeded", limit, reset_seconds }

​
GET /v1/scanner/scan/:id

Retrieve a specific scan by UUID. Scope required: read   Cost: 0

​
GET /v1/scanner/scans/by-domain/:domain

Look up the freshest scan across the shared corpus for a given domain. Scope required: read   Cost: 0 
curl -H "Authorization: Bearer $SCANNER_KEY" \
  https://scanner.getsly.ai/v1/scanner/scans/by-domain/shopify.com
Returns 404 if no scan exists for the domain.

​
GET /v1/scanner/scans

List scans with filters. Returns rows across all tenants — the shared scan corpus. Scope required: read   Cost: 0 Query parameters:
ParamNotes
categoryMerchant category filter
regionRegion filter
statuscompleted, failed, pending, etc.
min_scoreMinimum readiness_score
max_scoreMaximum readiness_score
page1-indexed
limitMax 100
Response: 
{
  "data": [ /* MerchantScan[] */ ],
  "pagination": { "page": 1, "limit": 20, "total": 1423, "totalPages": 72 }
}

​
GET /v1/scanner/scans/stats

Aggregate stats across the shared corpus. 
{
  "total": 1423,
  "completed": 1398,
  "avg_readiness_score": 54,
  "by_category": { "retail": 412, "saas": 338, "marketplace": 201, ... },
  "by_region": { "north_america": 720, "europe": 388, ... }
}

​
GET /v1/scanner/scans/protocol-adoption

Detected/functional adoption rates per protocol. 
{
  "acp": { "detected": 201, "functional": 128, "total": 1398, "adoption_rate": 14 },
  "x402": { "detected": 33,  "functional": 29,  "total": 1398, "adoption_rate": 2 },
  ...
}